Merge #642

642: Increase readability of binding docs r=toasteater a=Bromeon

Transforms some of the GDScript documentation markup to Rustdoc, using simple de-indentation and replacements. This makes bindings documentation, which has so far been a single huge code block, much more readable.

Adds the `unindent` crate, which has no further dependencies.

**Before:**
![before](https://user-images.githubusercontent.com/708488/101278044-f6db2800-37b8-11eb-8946-140e993bd843.png)

**After:**
![after](https://user-images.githubusercontent.com/708488/101278182-0d35b380-37ba-11eb-8b77-841b9b833da7.png)

This would be a first step. We could pull in the `regex` crate, to do smarter replacements such as `[constant HTTPClient.METHOD_GET]`, and possibly even link them using Rust 1.48's new feature ([doc](https://doc.rust-lang.org/rustdoc/linking-to-items-by-name.html), [announcement](https://blog.rust-lang.org/2020/11/19/Rust-1.48.html#easier-linking-in-rustdoc)).



Co-authored-by: Jan Haller <[email protected]>

Author: bors[bot]

bindings_generator/Cargo.toml

@@ -20,3 +20,4 @@ proc-macro2 = "1.0.6"
 quote = "1.0.2"
 syn = { version = "1.0", features = ["full", "extra-traits", "visit"] }
 miniserde = "=0.1.13"
+unindent = "0.1.7"

bindings_generator/src/class_docs.rs

@@ -110,18 +110,12 @@ impl GodotXMLDocs {
     }
 
     fn add_fn(&mut self, class: &str, method: &str, desc: &str, default_args: &[(&str, &str)]) {
-        let doc = desc.trim();
+        let mut doc = unindent::unindent(desc.trim());
 
         if doc.is_empty() && default_args.is_empty() {
             return;
         }
 
-        let mut doc = if !doc.is_empty() {
-            format!("```text\n{}\n```\n", doc)
-        } else {
-            String::new()
-        };
-
         if !default_args.is_empty() {
             doc.push_str("\n# Default Arguments");
 
@@ -130,7 +124,29 @@ impl GodotXMLDocs {
             }
         }
 
-        self.class_fn_desc
-            .insert((class.into(), method.into()), doc);
+        self.class_fn_desc.insert(
+            (class.into(), method.into()),
+            Self::reformat_as_rustdoc(doc),
+        );
+    }
+
+    /// Takes the Godot documentation markup and transforms it to Rustdoc.
+    /// Very basic approach with limitations, but already helps readability quite a bit.
+    fn reformat_as_rustdoc(godot_doc: String) -> String {
+        let gdscript_note = if godot_doc.contains("[codeblock]") {
+            "_Sample code is GDScript unless otherwise noted._\n\n"
+        } else {
+            ""
+        };
+
+        let translated = godot_doc
+            .replace("[code]", "`")
+            .replace("[/code]", "`")
+            .replace("[codeblock]", "```gdscript")
+            .replace("[/codeblock]", "```")
+            .replace("[b]", "**")
+            .replace("[/b]", "**");
+
+        format!("{}{}", gdscript_note, translated)
     }
 }

bindings_generator/src/documentation.rs

@@ -52,7 +52,8 @@ pub fn generate_class_documentation(api: &Api, class: &GodotClass) -> TokenStrea
     let official_docs = format!(
         r#"## Official documentation
 
-See the [documentation of this class]({url}) in the Godot engine's official documentation."#,
+See the [documentation of this class]({url}) in the Godot engine's official documentation.
+The method descriptions are generated from it and typically contain code samples in GDScript, not Rust."#,
         url = official_doc_url(class),
     );