feat: document crate

src/alejandra/src/format.rs

@@ -1,6 +1,10 @@
+/// Possibles results after formatting.
 #[derive(Clone)]
 pub enum Status {
+    /// An error ocurred, and its reason.
     Error(String),
+    /// Formatting was successful,
+    /// the file changed or not according to the boolean.
     Changed(bool),
 }
 
@@ -10,6 +14,8 @@ impl From<std::io::Error> for Status {
     }
 }
 
+/// Formats the content of `before` in-memory,
+/// and assume `path` in the displayed error messages
 pub fn in_memory(path: String, before: String) -> (Status, String) {
     let tokens = rnix::tokenizer::Tokenizer::new(&before);
     let ast = rnix::parser::parse(tokens);
@@ -39,6 +45,8 @@ pub fn in_memory(path: String, before: String) -> (Status, String) {
     }
 }
 
+/// Formats the file at `path`,
+/// optionally overriding it's contents if `in_place` is true.
 pub fn in_fs(path: String, in_place: bool) -> Status {
     use std::io::Write;
 

src/alejandra/src/lib.rs

@@ -1,3 +1,17 @@
+//! Alejandra takes your Nix code and re-formats it in a consistent style.
+//!
+//! For more information please visit the
+//! [Alejandra repository on GitHub](https://github.com/kamadorueda/alejandra).
+#![deny(missing_docs)]
+#![deny(rustdoc::bare_urls)]
+#![deny(rustdoc::broken_intra_doc_links)]
+#![deny(rustdoc::invalid_codeblock_attributes)]
+#![deny(rustdoc::invalid_html_tags)]
+#![deny(rustdoc::invalid_rust_codeblocks)]
+#![deny(rustdoc::missing_crate_level_docs)]
+#![deny(rustdoc::private_intra_doc_links)]
+#![deny(rustdoc::private_doc_tests)]
+
 #[cfg(any(
     all(
         target_arch = "aarch64",
@@ -30,9 +44,11 @@ static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;
 pub(crate) mod builder;
 pub(crate) mod children;
 pub(crate) mod children2;
+/// Functions for formatting Nix code.
 pub mod format;
 pub(crate) mod parsers;
 pub(crate) mod position;
 pub(crate) mod rules;
 pub(crate) mod utils;
+/// Metadata.
 pub mod version;

src/alejandra/src/version.rs

@@ -1 +1,2 @@
+/// The version of Alejandra.
 pub const VERSION: &str = "1.5.0";