add note & example about definition list

README.md

@@ -47,14 +47,20 @@ The following is an example of markdown documentation for new and current users
 
     # Arguments
 
-    - a: The first number
-    - b: The second number
+    a
+    : The first number
+    
+    b
+    : The second number
     
   */
   add = a: b: a + b;
 }
 ````
 
+> Note: Within nixpkgs the convention of using [definition-lists](https://www.markdownguide.org/extended-syntax/#definition-lists) for documenting arguments has been established.
+
+
 ## Custom nixdoc format (Legacy)
 
 You should consider migrating to the newer format described above.

doc/migration.md

@@ -50,8 +50,12 @@ filterAttrs =
   ```
   
   # Arguments
-  - **pred**: Predicate taking an attribute name and an attribute value, which returns `true` to include the attribute, or `false` to exclude the attribute.
-  - **set**: The attribute set to filter
+
+  **pred**
+  : Predicate taking an attribute name and an attribute value, which returns `true` to include the attribute, or `false` to exclude the attribute.
+  
+  **set**
+  : The attribute set to filter
 */
 filterAttrs =
   pred:
@@ -67,6 +71,8 @@ With the introduction of RFC145, there is a shift in how arguments are documente
 
 The approach to documenting single arguments has evolved. Instead of individual argument comments, document the function and its arguments together.
 
+> Note: Within nixpkgs the convention of using [definition-lists](https://www.markdownguide.org/extended-syntax/#definition-lists) for documenting arguments has been established.
+
 ```nix
 {
   /**

src/main.rs

@@ -116,7 +116,7 @@ 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> {
     let doc_comment = get_expr_docs(node);
-        
+
     doc_comment.map(|doc_comment| {
         shift_headings(
             &handle_indentation(&doc_comment).unwrap_or(String::new()),