feat: support additional doc comment markdown

Simulates formatting that Godot does not natively support in its limited
BBCode implementation, such as lists and footnotes, as best as possible.

Also fixes #811 as paragraphs are correctly formatted, without excessive
line breaks.

Author: adalinesimonian

godot-codegen/src/generator/central_files.rs

@@ -37,6 +37,7 @@ pub fn make_sys_central_code(api: &ExtensionApi) -> TokenStream {
             // This will need refactoring if VariantType is changed to a real enum.
             #[doc(hidden)]
             pub fn from_sys(enumerator: crate::GDExtensionVariantType) -> Self {
+                #[allow(clippy::unnecessary_cast)]
                 Self { ord: enumerator as i32 }
             }
 

godot-macros/src/docs.rs

@@ -146,12 +146,29 @@ fn xml_escape(value: String) -> String {
     result
 }
 
+/// Utility function that, given a line from a code comment, returns the line
+/// without the first leading space if it exists. This space is commonly used
+/// to separate the comment from the `///` that precedes it, but interferes
+/// with the formatting of the resulting Markdown.
+fn remove_initial_space(comment_line: &str) -> &str {
+    if comment_line.starts_with(" ") {
+        &comment_line[1..]
+    } else {
+        comment_line
+    }
+}
+
 /// Calls [`siphon_docs_from_attributes`] and converts the result to BBCode
 /// for Godot's consumption.
 fn make_docs_from_attributes(doc: &[Attribute]) -> Option<String> {
-    let doc = siphon_docs_from_attributes(doc)
+    let lines: Vec<String> = siphon_docs_from_attributes(doc).collect();
+
+    let doc = lines
+        .iter()
+        .map(|line| remove_initial_space(line))
         .collect::<Vec<_>>()
         .join("\n");
+
     (!doc.is_empty()).then(|| markdown_converter::to_bbcode(&doc))
 }