feat: support descriptions from comments

Check if the first node of a given nix file is a comment
and if so, insert them after the files heading while correcting
whitespace.

src/main.rs

@@ -394,6 +394,28 @@ fn collect_entries(root: rnix::Root, category: &str) -> Vec<ManualEntry> {
     vec![]
 }
 
+fn retrieve_description(
+    nix: &rnix::Root,
+    description: &str,
+    category: &str,
+) -> String {
+    format!(
+        "# {} {{#sec-functions-library-{}}}\n{}",
+        description,
+        category,
+        dedent(
+            &nix.syntax()
+                .first_child()
+                .and_then(|node|
+                          retrieve_doc_comment(&node, true)
+                          // we add two spaces to the beginning after comment
+                          // markers are stripped to keep dedent correct.
+                          .map(|mut s| {s.insert_str(0, "  "); s})
+                ) .unwrap_or_default()
+        )
+    )
+}
+
 fn main() {
     let mut output = io::stdout();
     let opts = Options::parse();
@@ -406,14 +428,14 @@ fn main() {
             .expect("could not read location information"),
     };
     let nix = rnix::Root::parse(&src).ok().expect("failed to parse input");
+    let description = retrieve_description(
+        &nix,
+        &opts.description,
+        &opts.category,
+    );
 
     // TODO: move this to commonmark.rs
-    writeln!(
-        output,
-        "# {} {{#sec-functions-library-{}}}\n",
-        &opts.description, opts.category
-    )
-    .expect("Failed to write header");
+    writeln!(output, "{}", description).expect("Failed to write header");
 
     for entry in collect_entries(nix, &opts.category) {
         entry
@@ -450,6 +472,26 @@ fn test_main() {
     insta::assert_snapshot!(output);
 }
 
+#[test]
+fn test_description_of_lib_debug() {
+    let mut output = Vec::new();
+    let src = fs::read_to_string("test/lib-debug.nix").unwrap();
+    let nix = rnix::Root::parse(&src).ok().expect("failed to parse input");
+    let category = "debug";
+    let desc = retrieve_description(&nix, &"Debug", category);
+    writeln!(output, "{}", desc).expect("Failed to write header");
+
+    for entry in collect_entries(nix, category) {
+        entry
+            .write_section(&Default::default(), &mut output)
+            .expect("Failed to write section")
+    }
+
+    let output = String::from_utf8(output).expect("not utf8");
+
+    insta::assert_snapshot!(output);
+}
+
 #[test]
 fn test_arg_formatting() {
     let mut output = Vec::new();