Merge pull request #4462 from lukewilliamboswell/rust-docs

Rust docs update #2

crates/compiler/alias_analysis/Cargo.toml

@@ -4,6 +4,7 @@ edition = "2021"
 license = "UPL-1.0"
 name = "roc_alias_analysis"
 version = "0.0.1"
+description = "Performs analysis and optimizations to remove unneeded reference counts at runtime, and supports in-place mutation."
 
 [dependencies]
 morphic_lib = {path = "../../vendor/morphic_lib"}

crates/compiler/alias_analysis/src/lib.rs

@@ -1,3 +1,5 @@
+//! Performs analysis and optimizations to remove unneeded [reference counts](https://en.wikipedia.org/wiki/Reference_counting)
+//! at runtime, and supports in-place mutation.
 use morphic_lib::TypeContext;
 use morphic_lib::{
     BlockExpr, BlockId, CalleeSpecVar, ConstDefBuilder, ConstName, EntryPointName, ExprContext,

crates/compiler/arena_pool/Cargo.toml

@@ -5,7 +5,7 @@ authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 repository = "https://github.com/roc-lang/roc"
 edition = "2021"
-description = "A CLI for Roc"
+description = "An implementation of an arena allocator designed for the compiler's workloads."
 
 [dependencies]
 roc_error_macros = { path = "../../error_macros" }

crates/compiler/arena_pool/src/lib.rs

@@ -1 +1,2 @@
+//! An implementation of an [arena allocator](https://mgravell.github.io/Pipelines.Sockets.Unofficial/docs/arenas.html) designed for the compiler's workloads.
 pub mod pool;

crates/compiler/build/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Responsible for coordinating building and linking of a Roc app with its host."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/build/src/lib.rs

@@ -1,3 +1,4 @@
+//! Responsible for coordinating building and linking of a Roc app with its host.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/builtins/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Provides the Roc functions and modules that are implicitly imported into every module."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/builtins/src/lib.rs

@@ -1,3 +1,4 @@
+//! Provides the Roc functions and modules that are implicitly imported into every module.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/can/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Canonicalize a roc abstract syntax tree, resolving symbols, re-ordering definitions, and preparing a module for type inference."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/can/src/lib.rs

@@ -1,3 +1,8 @@
+//! [Canonicalize](https://en.wikipedia.org/wiki/Canonicalization) a roc
+//! [abstract syntax tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree),
+//! [resolving symbols](https://stackoverflow.com/a/1175493/4200103),
+//! [re-ordering definitions](https://www.oreilly.com/library/view/c-high-performance/9781787120952/546b5677-9157-4333-bc90-16db696436ac.xhtml),
+//! and preparing a module for [type inference](https://en.wikipedia.org/wiki/Type_inference).
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/collections/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Domain-specific collections created for the needs of the compiler."
 
 [dependencies]
 fnv = "1.0.7"

crates/compiler/collections/src/lib.rs

@@ -1,3 +1,4 @@
+//! Domain-specific collections created for the needs of the compiler.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/constrain/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Responsible for building the set of constraints that are used during type inference of a program, and for gathering context needed for pleasant error messages when a type error occurs."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/constrain/src/lib.rs

@@ -1,3 +1,7 @@
+//! Responsible for building the set of constraints that are used during
+//! [type inference](https://en.wikipedia.org/wiki/Type_inference) of a program,
+//! and for gathering context needed for pleasant error messages when a type
+//! error occurs.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/debug_flags/Cargo.toml

@@ -4,5 +4,6 @@ version = "0.0.1"
 edition = "2021"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
+description = "Environment variables that can be toggled to aid debugging of the compiler itself."
 
 [dependencies]

crates/compiler/derive/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Provides auto-derivers for builtin abilities like `Hash` and `Decode`."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/exhaustive/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Provides exhaustiveness checking for Roc."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/exhaustive/src/lib.rs

@@ -1,5 +1,5 @@
-//! Exhaustiveness checking, based on "Warning for pattern matching" (Luc Maranget, 2007).
-//! http://moscova.inria.fr/~maranget/papers/warn/warn.pdf
+//! Exhaustiveness checking, based on [Warnings for pattern matching](http://moscova.inria.fr/~maranget/papers/warn/warn.pdf)
+//! (Luc Maranget, 2007).
 
 use roc_collections::all::{HumanIndex, MutMap};
 use roc_error_macros::internal_error;

crates/compiler/fmt/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "The roc code formatter."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/fmt/src/lib.rs

@@ -1,3 +1,4 @@
+//! The roc code formatter.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/gen_dev/src/lib.rs

@@ -1,3 +1,6 @@
+//! Provides the compiler backend to generate Roc binaries fast, for a nice
+//! developer experience. See [README.md](./compiler/gen_dev/README.md) for
+//! more information.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant, clippy::upper_case_acronyms)]

crates/compiler/gen_llvm/src/lib.rs

@@ -1,3 +1,5 @@
+//! Provides the LLVM backend to generate Roc binaries. Used to generate a
+//! binary with the fastest possible execution speed.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/gen_wasm/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 edition = "2021"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
+description = "Provides the WASM backend to generate Roc binaries."
 
 [dependencies]
 bitvec = "1"

crates/compiler/gen_wasm/src/lib.rs

@@ -1,3 +1,4 @@
+//! Provides the WASM backend to generate Roc binaries.
 mod backend;
 mod layout;
 mod low_level;

crates/compiler/ident/Cargo.toml

@@ -4,3 +4,4 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Implements data structures used for efficiently representing small strings, like identifiers."

crates/compiler/ident/src/lib.rs

@@ -1,3 +1,4 @@
+//! Implements data structures used for efficiently representing small strings, like identifiers.
 #![warn(clippy::dbg_macro)]
 
 use core::cmp::Ordering;

crates/compiler/intern/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Provides generic interners for concurrent and single-thread use cases."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/late_solve/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Provides type unification and solving primitives from the perspective of the compiler backend."
 
 [dependencies]
 roc_types = { path = "../types" }

crates/compiler/load/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Used to load a .roc file and coordinate the compiler pipeline, including parsing, type checking, and code generation."
 
 [dependencies]
 roc_load_internal = { path = "../load_internal" }

crates/compiler/load/src/lib.rs

@@ -1,3 +1,5 @@
+//! Used to load a .roc file and coordinate the compiler pipeline, including
+//! parsing, type checking, and [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler)).
 use bumpalo::Bump;
 use roc_can::module::{ExposedByModule, TypeState};
 use roc_collections::all::MutMap;

crates/compiler/load_internal/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "The internal implementation of roc_load, separate from roc_load to support caching."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/load_internal/src/lib.rs

@@ -1,3 +1,4 @@
+//! The internal implementation of roc_load, separate from roc_load to support caching.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/module/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 edition = "2021"
 license = "UPL-1.0"
+description = "Implements data structures used for efficiently representing unique modules and identifiers in Roc programs."
 
 [dependencies]
 roc_region = { path = "../region" }

crates/compiler/module/src/lib.rs

@@ -1,3 +1,5 @@
+//! Implements data structures used for efficiently representing unique modules
+//! and identifiers in Roc programs.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant, clippy::upper_case_acronyms)]

crates/compiler/mono/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Roc's main intermediate representation (IR), which is responsible for monomorphization, defunctionalization, inserting ref-count instructions, and transforming a Roc program into a form that is easy to consume by a backend."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/mono/src/lib.rs

@@ -1,3 +1,8 @@
+//! Roc's main intermediate representation (IR), which is responsible for
+//! [monomorphization](https://en.wikipedia.org/wiki/Monomorphization),
+//! defunctionalization, inserting [ref-count](https://en.wikipedia.org/wiki/Reference_counting)
+//! instructions, and transforming a Roc program into a form that is easy to
+//! consume by a backend.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant, clippy::upper_case_acronyms)]

crates/compiler/parse/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Implements the Roc parser, which transforms a textual representation of a Roc program to an AST."
 
 [features]
 "parse_debug_trace" = []

crates/compiler/parse/src/lib.rs

@@ -1,3 +1,5 @@
+//! Implements the Roc parser, which transforms a textual representation of a
+//! Roc program to an [abstract syntax tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree).
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/problem/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Provides types to describe problems that can occur when compiling Roc code."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/problem/src/lib.rs

@@ -1,3 +1,4 @@
+//! Provides types to describe problems that can occur when compiling Roc code.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/region/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Data structures for storing source-code-location information, used heavily for contextual error messages."
 
 [dependencies]
 static_assertions = "1.1.0"

crates/compiler/region/src/lib.rs

@@ -1,3 +1,5 @@
+//! Data structures for storing source-code-location information, used heavily
+//! for contextual error messages.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/roc_target/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Provides types and helpers for compiler targets such as default_x86_64."
 
 [dependencies]
 target-lexicon = "0.12.3"

crates/compiler/roc_target/src/lib.rs

@@ -1,3 +1,4 @@
+//! Provides types and helpers for compiler targets such as `default_x86_64`.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/serialize/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Provides helpers for serializing and deserializing to/from bytes."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/serialize/src/lib.rs

@@ -1 +1,2 @@
+//! Provides helpers for serializing and deserializing to/from bytes.
 pub mod bytes;

crates/compiler/solve/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "The entry point of Roc's type inference system. Implements type inference and specialization of abilities."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/solve/src/lib.rs

@@ -1,3 +1,5 @@
+//! The entry point of Roc's [type inference](https://en.wikipedia.org/wiki/Type_inference)
+//! system. Implements type inference and specialization of abilities.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/solve_problem/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Provides types to describe problems that can occur during solving."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/solve_problem/src/lib.rs

@@ -1,3 +1,4 @@
+//! Provides types to describe problems that can occur during solving.
 use roc_can::expected::{Expected, PExpected};
 use roc_module::{ident::Lowercase, symbol::Symbol};
 use roc_problem::can::CycleEntry;

crates/compiler/str/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Provides a Roc Str with reference-counting so that it may be mutated in-place."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/str/src/lib.rs

@@ -1,3 +1,8 @@
+//! Provides `Roc` styled collection [reference counting](https://en.wikipedia.org/wiki/Reference_counting). 
+//! This means the collection may or may not be safe to mutate in-place, may or 
+//! may not be reference counted, and may or may not need to be freed when no 
+//! longer in use. Whether each of these is true for a given collection can be 
+//! determined by inspecting that collection at runtime.
 #![crate_type = "lib"]
 #![no_std]
 

crates/compiler/test_derive/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Tests Roc's auto-derivers."
 
 [[test]]
 name = "test_derive"

crates/compiler/test_gen/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Contains all of Roc's code generation tests."
 
 [[test]]
 name = "test_gen"

crates/compiler/test_gen/src/lib.rs

@@ -1,2 +1,4 @@
+//! Contains all of Roc's [code generation](https://en.wikipedia.org/wiki/Code_generation_(compiler))
+//! tests.
 #[cfg(test)]
 pub mod helpers;

crates/compiler/test_mono/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Tests Roc's generation of the mono intermediate representation."
 
 [[test]]
 name = "test_mono"

crates/compiler/test_mono_macros/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Macros for use in test_mono."
 
 [lib]
 proc-macro = true

crates/compiler/test_mono_macros/src/lib.rs

@@ -1,3 +1,4 @@
+//! Macros for use in `test_mono`.
 extern crate proc_macro;
 
 use proc_macro::TokenStream;

crates/compiler/types/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.0.1"
 authors = ["The Roc Contributors"]
 license = "UPL-1.0"
 edition = "2021"
+description = "Various representations and utilities for dealing with types in the Roc compiler."
 
 [dependencies]
 roc_collections = { path = "../collections" }

crates/compiler/types/src/lib.rs

@@ -1,3 +1,4 @@
+//! Various representations and utilities for dealing with types in the Roc compiler.
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]

crates/compiler/unify/Cargo.toml

@@ -4,6 +4,7 @@ edition = "2021"
 license = "UPL-1.0"
 name = "roc_unify"
 version = "0.0.1"
+description = "Implements Roc's unification algorithm, the heartstone of Roc's type inference."
 
 [dependencies]
 bitflags = "1.3.2"

crates/compiler/unify/src/lib.rs

@@ -1,3 +1,5 @@
+//! Implements Roc's unification algorithm, the heartstone of Roc's
+//! [type inference](https://en.wikipedia.org/wiki/Type_inference).
 #![warn(clippy::dbg_macro)]
 // See github.com/roc-lang/roc/issues/800 for discussion of the large_enum_variant check.
 #![allow(clippy::large_enum_variant)]