Add some docs

crates/frontend/src/ast.rs

@@ -16,6 +16,9 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with Kerolox. If not, see <https://www.gnu.org/licenses/>.
 
+//! The "ast" stage of the frontend: extract structured information about a raw
+//! tree-sitter abstract syntax tree of a file.
+
 use std::{convert::Infallible, fmt::Display, str::FromStr, sync::Arc};
 
 use ir::EnumParse;

crates/frontend/src/lib.rs

@@ -16,19 +16,28 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with Kerolox. If not, see <https://www.gnu.org/licenses/>.
 
-// TODO: top-level docs
-// TODO: crate-wide missing docs warning
+//! The framework for parsing and analysis of Kerolox syntax.
+//!
+//! The frontend is organized into several *stages*, each of which provide more
+//! information about a Kerolox workspace:
+//! - [ast] parses raw tree-sitter ASTs of Kerolox code into structured Rust types
+//! - [resolve] determines the concrete semantic objects that names and path refer to
+
+#![warn(missing_docs)]
 
 use salsa::Database;
 
 use crate::{diagnostic::DynDiagnostic, workspace::Workspace};
 
+// TODO: more top-level docs
+
 pub mod ast;
 pub mod diagnostic;
 pub mod editor;
 pub mod resolve;
 pub mod workspace;
 
+/// Frequently-used imports across all frontend stages.
 pub mod prelude {
     pub use kerolox_ir as ir;
     pub use salsa::{Database, Setter};
@@ -41,7 +50,8 @@ pub mod prelude {
     };
 }
 
-// TODO: make IR compilation w/ errors the top-level entrypoint for diagnostic generation
+/// Utility function to analyze a workspace with all stages and return found diagnostics.
 pub fn check_all_diagnostics(_db: &dyn Database, _ws: Workspace) -> Vec<&DynDiagnostic> {
+    // TODO: make IR compilation w/ errors the top-level entrypoint for diagnostic generation
     Vec::new()
 }

crates/frontend/src/resolve.rs

@@ -16,24 +16,39 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with Kerolox. If not, see <https://www.gnu.org/licenses/>.
 
+//! The "resolve" stage of the frontend: match up names of objects with the
+//! semantic objects they refer to.
+
 use std::collections::BTreeMap;
 
 use salsa::Update;
 
 use crate::prelude::*;
 
+/// A complete definition for a Kerolox scope which can be accessed by paths.
 #[salsa::tracked]
 pub struct Namespace<'db> {
+    /// A mapping of items within a namespace to the names they can be referred to as.
     #[returns(ref)]
     pub items: BTreeMap<String, NamespaceItem<'db>>,
 }
 
+/// A generic item in a [Namespace].
 #[derive(Clone, PartialEq, Eq, Hash, Update)]
 pub enum NamespaceItem<'db> {
+    /// A user-defined file.
     File(workspace::File),
+
+    /// A nested [Namespace] definition.
     Namespace(Namespace<'db>),
+
+    /// An abstract relation parsed from a file.
     Relation(ast::Relation<'db>),
+
+    /// An abstract type alias parsed from a file.
     TypeAlias(ast::TypeAlias<'db>),
+
+    /// Unknown: the name is valid, but its definition is somehow incomplete.
     Unknown,
 }