From c0693b495efb79d2ccf308312b48145280e4c42b Mon Sep 17 00:00:00 2001
From: Kevin Amado <kamadorueda@gmail.com>
Date: Tue, 12 Jul 2022 13:20:18 -0600
Subject: [PATCH] feat: document crate

---
 src/alejandra/src/format.rs  |  8 ++++++++
 src/alejandra/src/lib.rs     | 16 ++++++++++++++++
 src/alejandra/src/version.rs |  1 +
 3 files changed, 25 insertions(+)

diff --git a/src/alejandra/src/format.rs b/src/alejandra/src/format.rs
index 835766d..e5ccd0a 100644
--- a/src/alejandra/src/format.rs
+++ b/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;
 
diff --git a/src/alejandra/src/lib.rs b/src/alejandra/src/lib.rs
index d331801..84446b9 100644
--- a/src/alejandra/src/lib.rs
+++ b/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;
diff --git a/src/alejandra/src/version.rs b/src/alejandra/src/version.rs
index b076346..ab91a14 100644
--- a/src/alejandra/src/version.rs
+++ b/src/alejandra/src/version.rs
@@ -1 +1,2 @@
+/// The version of Alejandra.
 pub const VERSION: &str = "1.5.0";