Add bidirectional links between api::MyClass and api::my_class; remove empty nested modules

Author: Bromeon

bindings_generator/src/api.rs

@@ -160,6 +160,11 @@ impl GodotClass {
     pub fn is_getter(&self, name: &str) -> bool {
         self.properties.iter().any(|p| p.getter == name)
     }
+
+    /// Whether there is a snake_case module containing related symbols (nested types in C++)
+    pub fn has_related_module(&self) -> bool {
+        !self.enums.is_empty()
+    }
 }
 
 pub type ConstantName = String;

bindings_generator/src/documentation.rs

@@ -17,6 +17,17 @@ pub fn official_doc_url(class: &GodotClass) -> String {
     )
 }
 
+pub fn generate_module_doc(class: &GodotClass) -> TokenStream {
+    let module_doc = format!(
+        "This module contains types related to the API class [`{m}`][super::{m}].",
+        m = class.name
+    );
+
+    quote! {
+        #![doc=#module_doc]
+    }
+}
+
 pub fn generate_class_documentation(api: &Api, class: &GodotClass) -> TokenStream {
     let has_parent = !class.base_class.is_empty();
     let singleton_str = if class.singleton { "singleton " } else { "" };
@@ -26,7 +37,7 @@ pub fn generate_class_documentation(api: &Api, class: &GodotClass) -> TokenStrea
         "unsafe"
     };
 
-    let summary_doc = if &class.name == "Reference" {
+    let mut summary_doc = if &class.name == "Reference" {
         "Base class of all reference-counted types. Inherits `Object`.".into()
     } else if &class.name == "Object" {
         "The base class of most Godot classes.".into()
@@ -37,18 +48,20 @@ pub fn generate_class_documentation(api: &Api, class: &GodotClass) -> TokenStrea
             name = class.name,
             base_class = class.base_class,
             ownership_type = ownership_type,
-            singleton = singleton_str
+            singleton = singleton_str,
         )
     } else {
         format!(
-            "`{api_type} {singleton}class {name}` ({ownership_type}).",
+            "`{api_type} {singleton}class {name}` ({ownership_type})",
             api_type = class.api_type,
             name = class.name,
             ownership_type = ownership_type,
             singleton = singleton_str,
         )
     };
 
+    append_related_module(&mut summary_doc, class);
+
     let official_docs = format!(
         r#"## Official documentation
 
@@ -145,3 +158,16 @@ fn list_base_classes(output: &mut impl Write, api: &Api, parent_name: &str) -> G
 
     Ok(())
 }
+
+// If present, links to the module with related (C++: nested) types.
+fn append_related_module(string: &mut String, class: &GodotClass) {
+    use std::fmt::Write;
+    if class.has_related_module() {
+        write!(
+            string,
+            "\n\nThis class has related types in the [`{m}`][super::{m}] module.",
+            m = class.module()
+        )
+        .expect("append to string via write!");
+    }
+}

bindings_generator/src/lib.rs

@@ -38,20 +38,20 @@ use std::io;
 
 pub type GeneratorResult<T = ()> = Result<T, io::Error>;
 
-pub struct BindingResult {
-    pub class_bindings: HashMap<String, TokenStream>,
+pub struct BindingResult<'a> {
+    pub class_bindings: Vec<(&'a GodotClass, TokenStream)>,
     pub icalls: TokenStream,
 }
 
-pub fn generate_bindings(api: &Api, docs: Option<&GodotXmlDocs>) -> BindingResult {
+pub fn generate_bindings<'a>(api: &'a Api, docs: Option<&GodotXmlDocs>) -> BindingResult<'a> {
     let mut icalls = HashMap::new();
 
     let class_bindings = api
         .classes
         .iter()
         .map(|class| {
             (
-                class.name.clone(),
+                class,
                 generate_class_bindings(api, class, &mut icalls, docs),
             )
         })
@@ -84,6 +84,7 @@ fn generate_class_bindings(
 ) -> TokenStream {
     // types and methods
     let types_and_methods = {
+        let module_doc = generate_module_doc(class);
         let class_doc = generate_class_documentation(api, class);
         let class_struct = generate_class_struct(class, class_doc);
 
@@ -98,6 +99,7 @@ fn generate_class_bindings(
         let class_impl = generate_class_impl(class, icalls, docs);
 
         quote! {
+            #module_doc
             #class_struct
             #enums
             #constants

gdnative-bindings/build.rs

@@ -50,18 +50,26 @@ fn generate(
     generated_file: &mut BufWriter<File>,
     binding_res: &BindingResult,
 ) {
-    for (class_name, code) in &binding_res.class_bindings {
+    // Note: 'use super::*;' needs to be after content, as the latter may contain #![doc] attributes,
+    // which need to be at the beginning of the module
+    for (class, code) in &binding_res.class_bindings {
+        let modifier = if class.has_related_module() {
+            "pub"
+        } else {
+            "pub(crate)"
+        };
         write!(
             generated_file,
             r#"
-            pub mod {mod_name} {{
-                use super::*;
+            {modifier} mod {mod_name} {{
                 {content}
+                use super::*;
             }}
             pub use crate::generated::{mod_name}::private::{class_name};
             "#,
-            mod_name = module_name_from_class_name(class_name),
-            class_name = class_name,
+            modifier = modifier,
+            mod_name = module_name_from_class_name(&class.name),
+            class_name = class.name,
             content = code,
         )
         .unwrap();
@@ -76,16 +84,18 @@ fn generate(
     generated_file: &mut BufWriter<File>,
     binding_res: &BindingResult,
 ) {
-    for (class_name, code) in &binding_res.class_bindings {
-        let mod_name = module_name_from_class_name(class_name);
+    for (class, code) in &binding_res.class_bindings {
+        let mod_name = module_name_from_class_name(&class.name);
 
         let mod_path = out_path.join(format!("{}.rs", mod_name));
         let mut mod_output = BufWriter::new(File::create(&mod_path).unwrap());
 
         write!(
             &mut mod_output,
-            r#"use super::*;
-            {content}"#,
+            r#"
+            {content}
+            use super::*;
+            "#,
             content = code,
         )
         .unwrap();
@@ -96,16 +106,22 @@ fn generate(
             format_file(&mod_path);
         }
 
+        let modifier = if class.has_related_module() {
+            "pub"
+        } else {
+            "pub(crate)"
+        };
         writeln!(
             generated_file,
             r#"
             #[path = {:?}]
-            pub mod {mod_name};
+            {modifier} mod {mod_name};
             pub use crate::generated::{mod_name}::private::{class_name};
             "#,
             mod_path.display(),
+            modifier = modifier,
             mod_name = mod_name,
-            class_name = class_name,
+            class_name = class.name,
         )
         .unwrap();
     }