shift markdown headings, currently needed for manual rendering

src/comment.rs

@@ -20,7 +20,7 @@ impl DocComment for ast::Comment {
     fn doc_text(&self) -> Option<&str> {
         let text = self.syntax().text();
         // Check whether this is a doc-comment
-        if text.starts_with(r#"/**"#) && self.text().starts_with("*") {
+        if text.starts_with(r#"/**"#) && self.text().starts_with('*') {
             match text.strip_prefix(r#"/**"#) {
                 Some(t) => t.strip_suffix(r#"*/"#),
                 _ => None,
@@ -61,7 +61,7 @@ pub fn get_expr_docs(expr: &SyntaxNode) -> Option<String> {
         match_ast! {
             match parent {
                 ast::AttrpathValue(_) => {
-                    if let Some(doc_comment) = get_doc_comment(&parent) {
+                    if let Some(doc_comment) = get_doc_comment(parent) {
                         doc_comment.doc_text().map(|v| v.to_owned())
                     }else{
                         None
@@ -90,13 +90,12 @@ fn get_doc_comment(expr: &SyntaxNode) -> Option<ast::Comment> {
     loop {
         match prev {
             Some(rnix::NodeOrToken::Token(ref token)) => {
-                println!("TOKEN {token:?}");
                 match_ast! { match token {
                     ast::Whitespace(_) => {
                         prev = token.prev_sibling_or_token();
                     },
                     ast::Comment(it) => {
-                        if let Some(_) = it.doc_text() {
+                        if it.doc_text().is_some() {
                             break Some(it);
                         }else{
                             //Ignore non-doc comments.

src/main.rs

@@ -170,10 +170,17 @@ fn retrieve_doc_item(node: &AttrpathValue) -> Option<DocItem> {
     // If there is a doc comment according to RFC145 just return it.
     let doc_comment = get_expr_docs(node.syntax());
     if let Some(doc_comment) = doc_comment {
+        let doc = shift_headings(
+            &handle_indentation(&doc_comment).unwrap_or(String::new()),
+            // H1 to H4 can be used in the doc-comment with the current rendering.
+            // They will be shifted to H3, H6
+            // H1 and H2 are currently used by the outer rendering. (category and function name)
+            2,
+        );
         return Some(DocItem {
             name: item_name,
             comment: DocComment {
-                doc: doc_comment,
+                doc,
                 doc_type: None,
                 example: None,
             },
@@ -236,6 +243,66 @@ fn handle_indentation(raw: &str) -> Option<String> {
     Some(result.trim().to_owned()).filter(|s| !s.is_empty())
 }
 
+/// Shift down markdown headings
+///
+/// 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.
+/// by default this function makes sure, headings don't exceed the H6 boundary.
+/// levels := 2;
+/// ...
+/// H4 -> H6
+/// H6 -> H6
+///
+fn shift_headings(raw: &str, levels: usize) -> String {
+    let mut result = String::new();
+    for line in raw.lines() {
+        if line.trim_start().starts_with('#') {
+            result.push_str(&format!("{}\n", &handle_heading(line, levels)));
+        } else {
+            result.push_str(&format!("{line}\n"));
+        }
+    }
+    result
+}
+
+// Dumb heading parser.
+fn handle_heading(line: &str, levels: usize) -> String {
+    let chars = line.chars();
+
+    let mut leading_trivials: String = String::new();
+    let mut hashes = String::new();
+    let mut rest = String::new();
+    for char in chars {
+        match char {
+            ' ' | '\t' => {
+                // only collect trivial before the initial hash
+                if hashes.is_empty() {
+                    leading_trivials.push(char)
+                }
+            }
+            '#' => {
+                // only collect hashes if no other tokens
+                if rest.is_empty() {
+                    hashes.push(char)
+                }
+            }
+            _ => rest.push(char),
+        }
+    }
+    let new_hashes = match hashes.len() + levels {
+        // We reached the maximum heading size.
+        6.. => "#".repeat(6),
+        _ => "#".repeat(hashes.len() + levels),
+    };
+
+    format!("{leading_trivials}{new_hashes}{rest}")
+}
+
 /// Dumb, mutable, hacky doc comment "parser".
 fn parse_doc_comment(raw: &str) -> DocComment {
     enum ParseState {