typos and minor fixup

CHANGELOG.md

@@ -10,7 +10,7 @@
 
 - **Legacy Custom Format:** The custom nixdoc format is now considered a legacy feature. We plan to phase it out in future versions to streamline documentation practices.
 - We encourage users to transition to the official doc-comment format introduced in this release.
-- We will continue to maintain the legacy format, we will not accept new features or enhancements for it. This decision allows for a period of transition to the new documentation practices.
+- For now we will continue to maintain the legacy format, but will not accept new features or enhancements for it. This decision allows for a period of transition to the new documentation practices.
 
 See [Migration guide](./doc/migration.md) for smooth transition
 
@@ -20,7 +20,7 @@ See [Migration guide](./doc/migration.md) for smooth transition
 
 ## 2.7.0
 
-- Added support to customize the attribute set prefix, which was previously hardcoded to `lib`.
+- Added support to customise the attribute set prefix, which was previously hardcoded to `lib`.
   The default is still `lib`, but you can pass `--prefix` now to use something else like `utils`.
 
   By @Janik-Haag in https://github.com/nix-community/nixdoc/pull/97

README.md

@@ -11,12 +11,12 @@ function set.
 ## Comment format
 
 This tool implements a subset of the doc-comment standard specified in [RFC-145/doc-comments](https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md).
-But, it is currently limited to generating documentation for statically analyzable attribute paths only.
+But, it is currently limited to generating documentation for statically analysable attribute paths only.
 In the future, it could be the role of a Nix interpreter to obtain the values to be documented and their doc-comments.
 
 It is important to start doc-comments with the additional asterisk (`*`) -> `/**` which renders as a doc-comment.
 
-The content of the doc-comment should be some markdown. ( See [Commonmark](https://spec.commonmark.org/0.30/) specification)
+The content of the doc-comment should conform to the [Commonmark](https://spec.commonmark.org/0.30/) specification.
 
 ### Example
 

doc/migration.md

@@ -74,7 +74,8 @@ The approach to documenting single arguments has evolved. Instead of individual
   
   # Arguments
   
-  - **x**: The value to be returned.
+  `x` (Any)
+  : The value to be returned.
   
   */
   id = x: x;
@@ -105,7 +106,7 @@ Structured arguments can be documented (described in RFC145 as 'lambda formals')
 ```nix
 {
   /**
-  * The `add` function calculates the sum of `a` and `b`.
+  The `add` function calculates the sum of `a` and `b`.
   */
   add = { 
       /** The first number to add. */

src/format.rs

@@ -49,13 +49,13 @@ pub fn handle_indentation(raw: &str) -> Option<String> {
 
 /// Shift down markdown headings
 ///
-/// Performs a line-wise matching to ' # Heading '
+/// Performs a line-wise matching to '# Heading '
 ///
 /// Counts the current numbers of '#' and adds levels: [usize] to them
 /// levels := 1; gives
 /// '# Heading' -> '## Heading'
 ///
-/// Markdown has 6 levels of headings. Everything beyond that (e.g., H7) may produce unexpected renderings.
+/// Commonmark markdown has 6 levels of headings. Everything beyond that (e.g., H7) is not supported and may produce unexpected renderings.
 /// by default this function makes sure, headings don't exceed the H6 boundary.
 /// levels := 2;
 /// ...
@@ -78,15 +78,15 @@ pub fn shift_headings(raw: &str, levels: usize) -> String {
 pub fn handle_heading(line: &str, levels: usize) -> String {
     let chars = line.chars();
 
-    let mut leading_trivials: String = String::new();
+    // let mut leading_trivials: String = String::new();
     let mut hashes = String::new();
     let mut rest = String::new();
     for char in chars {
         match char {
-            ' ' | '\t' if hashes.is_empty() => {
-                // only collect trivial before the initial hash
-                leading_trivials.push(char)
-            }
+            // ' ' | '\t' if hashes.is_empty() => {
+            //     // only collect trivial before the initial hash
+            //     leading_trivials.push(char)
+            // }
             '#' if rest.is_empty() => {
                 // only collect hashes if no other tokens
                 hashes.push(char)
@@ -100,5 +100,5 @@ pub fn handle_heading(line: &str, levels: usize) -> String {
         _ => "#".repeat(hashes.len() + levels),
     };
 
-    format!("{leading_trivials}{new_hashes} {rest}")
+    format!("{new_hashes}{rest}")
 }

src/main.rs

@@ -113,20 +113,10 @@ impl DocItem {
     }
 }
 
+/// Returns a rfc145 doc-comment if one is present
 pub fn retrieve_doc_comment(node: &SyntaxNode, shift_headings_by: Option<usize>) -> Option<String> {
-    // Return a rfc145 doc-comment if one is present
-    // Otherwise do the legacy parsing
-    // If there is a doc comment according to RFC145 just return it.
-    let doc_comment = match node.kind() {
-        // NODE_IDENT_PARAM: Special case, for backwards compatibility with function args
-        // In rfc145 this is equivalent with lookup of the lambda docs of the partial function.
-        // a: /** Doc comment */b:
-        // NODE_LAMBDA(b:) <- (parent of IDENT_PARAM)
-        //  NODE_IDENT_PARAM(b)
-        SyntaxKind::NODE_IDENT_PARAM => get_expr_docs(&node.parent().unwrap()),
-        _ => get_expr_docs(node),
-    };
-
+    let doc_comment = get_expr_docs(node);
+
     doc_comment.map(|doc_comment| {
         shift_headings(
             &handle_indentation(&doc_comment).unwrap_or(String::new()),