docs

Author: bend-n

godot-core/src/init/mod.rs

@@ -119,6 +119,77 @@ unsafe extern "C" fn ffi_deinitialize_layer<E: ExtensionLibrary>(
     });
 }
 
+#[cfg(since_api = "4.3")]
+/// # Safety
+///
+/// The Godot binding must have been initialized before calling this function.
+///
+/// If "experimental-threads" is not enabled, then this must be called from the same thread that the bindings were initialized from.
+unsafe fn register_docs() {
+    use crate::registry::plugin::PluginItem;
+    use std::collections::{hash_map::Entry, HashMap};
+    #[derive(Default)]
+    struct DocPieces {
+        /// base, description, members
+        definition: [&'static str; 3],
+        /// methods, signals, constants
+        inherent: [&'static str; 3],
+        imethods: &'static str,
+    }
+
+    let mut map = HashMap::<&'static str, DocPieces>::new();
+    crate::private::iterate_plugins(|x| match x.item {
+        PluginItem::InherentImpl { docs, .. } => match map.entry(x.class_name.as_str()) {
+            Entry::Occupied(x) => x.into_mut().inherent = docs,
+            Entry::Vacant(x) => drop(x.insert(DocPieces {
+                inherent: docs,
+                ..Default::default()
+            })),
+        },
+        PluginItem::ITraitImpl { docs, .. } => match map.entry(x.class_name.as_str()) {
+            Entry::Occupied(x) => x.into_mut().imethods = docs,
+            Entry::Vacant(x) => drop(x.insert(DocPieces {
+                imethods: docs,
+                ..Default::default()
+            })),
+        },
+        PluginItem::Struct { docs, .. } => match map.entry(x.class_name.as_str()) {
+            Entry::Occupied(x) => x.into_mut().definition = docs,
+            Entry::Vacant(x) => drop(x.insert(DocPieces {
+                definition: docs,
+                ..Default::default()
+            })),
+        },
+    });
+    for (
+        class,
+        DocPieces {
+            definition: [base, desc, members],
+            inherent: [methods, signals, constants],
+            imethods,
+        },
+    ) in map
+    {
+        let brief = desc.lines().next().unwrap_or_default();
+        let xml = format!(
+            r#"
+<?xml version="1.0" encoding="UTF-8"?>
+<class name="{class}" inherits="{base}" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+<brief_description>{brief}</brief_description>
+<description>{desc}</description>
+<methods>{methods}{imethods}</methods>
+<constants>{constants}</constants>
+<signals>{signals}</signals>
+<members>{members}</members>
+</class>"#
+        );
+        crate::sys::interface_fn!(editor_help_load_xml_from_utf8_chars_and_len)(
+            xml.as_ptr().cast(),
+            xml.len() as i64,
+        );
+    }
+}
+
 /// Tasks needed to be done by gdext internally upon loading an initialization level. Called before user code.
 fn gdext_on_level_init(level: InitLevel) {
     // SAFETY: we are in the main thread, during initialization, no other logic is happening.
@@ -136,6 +207,8 @@ fn gdext_on_level_init(level: InitLevel) {
                 ensure_godot_features_compatible();
             }
             InitLevel::Editor => {
+                #[cfg(since_api = "4.3")]
+                register_docs();
                 sys::load_class_method_table(sys::ClassApiLevel::Editor);
             }
         }

godot-core/src/registry/class.rs

@@ -232,6 +232,7 @@ fn fill_class_info(item: PluginItem, c: &mut ClassRegistrationInfo) {
             is_editor_plugin,
             is_hidden,
             is_instantiable,
+            ..
         } => {
             c.parent_class_name = Some(base_class_name);
             c.default_virtual_fn = default_get_virtual_fn;
@@ -282,6 +283,7 @@ fn fill_class_info(item: PluginItem, c: &mut ClassRegistrationInfo) {
 
         PluginItem::InherentImpl {
             register_methods_constants_fn,
+            ..
         } => {
             c.register_methods_constants_fn = Some(register_methods_constants_fn);
         }
@@ -299,6 +301,7 @@ fn fill_class_info(item: PluginItem, c: &mut ClassRegistrationInfo) {
             user_free_property_list_fn,
             user_property_can_revert_fn,
             user_property_get_revert_fn,
+            ..
         } => {
             c.user_register_fn = user_register_fn;
 

godot-core/src/registry/plugin.rs

@@ -96,6 +96,8 @@ pub enum PluginItem {
 
         /// Whether the class has a default constructor.
         is_instantiable: bool,
+        /// Base, Description, Members.
+        docs: [&'static str; 3],
     },
 
     /// Collected from `#[godot_api] impl MyClass`.
@@ -104,10 +106,14 @@ pub enum PluginItem {
         ///
         /// Always present since that's the entire point of this `impl` block.
         register_methods_constants_fn: ErasedRegisterFn,
+        /// Method, Signal, Constant documentation.
+        docs: [&'static str; 3],
     },
 
     /// Collected from `#[godot_api] impl I... for MyClass`.
     ITraitImpl {
+        /// Virtual method documentation.
+        docs: &'static str,
         /// Callback to user-defined `register_class` function.
         user_register_fn: Option<ErasedRegisterFn>,
 

godot-macros/Cargo.toml

@@ -12,6 +12,7 @@ homepage = "https://godot-rust.github.io"
 
 [features]
 api-custom = ["godot-bindings/api-custom"]
+docs = ["dep:markdown"]
 
 [lib]
 proc-macro = true
@@ -21,6 +22,8 @@ proc-macro = true
 proc-macro2 = "1.0.63"
 quote = "1.0.29"
 
+# Enabled by `docs`
+markdown = { version = "1.0.0-alpha.17", optional = true }
 venial = "0.6"
 
 [build-dependencies]

godot-macros/src/class/data_models/constant.rs

@@ -10,6 +10,7 @@ use crate::{util, ParseResult};
 use proc_macro2::{Ident, TokenStream};
 use quote::quote;
 
+#[derive(Clone)]
 pub struct ConstDefinition {
     pub raw_constant: venial::Constant,
 }

godot-macros/src/class/data_models/field.rs

@@ -7,6 +7,7 @@
 
 use crate::class::{FieldExport, FieldVar};
 use proc_macro2::{Ident, TokenStream};
+use venial::Attribute;
 
 pub struct Field {
     pub name: Ident,
@@ -15,6 +16,7 @@ pub struct Field {
     pub var: Option<FieldVar>,
     pub export: Option<FieldExport>,
     pub is_onready: bool,
+    pub attributes: Vec<Attribute>,
 }
 
 impl Field {
@@ -26,6 +28,7 @@ impl Field {
             var: None,
             export: None,
             is_onready: false,
+            attributes: field.attributes.clone(),
         }
     }
 }

godot-macros/src/class/data_models/func.rs

@@ -11,6 +11,7 @@ use proc_macro2::{Group, Ident, TokenStream, TokenTree};
 use quote::{format_ident, quote};
 
 /// Information used for registering a Rust function with Godot.
+#[derive(Clone)]
 pub struct FuncDefinition {
     /// Refined signature, with higher level info and renamed parameters.
     pub signature_info: SignatureInfo,
@@ -158,7 +159,7 @@ pub enum ReceiverType {
     Static,
 }
 
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub struct SignatureInfo {
     pub method_name: Ident,
     pub receiver_type: ReceiverType,

godot-macros/src/class/data_models/inherent_impl.rs

@@ -51,14 +51,21 @@ pub fn transform_inherent_impl(mut impl_block: venial::Impl) -> ParseResult<Toke
     let (funcs, signals) = process_godot_fns(&class_name, &mut impl_block)?;
     let consts = process_godot_constants(&mut impl_block)?;
 
-    let signal_registrations = make_signal_registrations(signals, &class_name_obj);
+    let signal_registrations = make_signal_registrations(signals.clone(), &class_name_obj);
 
     let method_registrations: Vec<TokenStream> = funcs
+        .clone()
         .into_iter()
         .map(|func_def| make_method_registration(&class_name, func_def))
         .collect::<ParseResult<Vec<TokenStream>>>()?; // <- FIXME transpose this
 
-    let constant_registration = make_constant_registration(consts, &class_name, &class_name_obj)?;
+    let constant_registration =
+        make_constant_registration(consts.clone(), &class_name, &class_name_obj)?;
+
+    #[cfg(feature = "docs")]
+    let docs = crate::docs::make_inherent_impl_docs(funcs, consts, signals);
+    #[cfg(not(feature = "docs"))]
+    let docs = quote! { [""; 3] };
 
     let result = quote! {
         #impl_block
@@ -77,6 +84,7 @@ pub fn transform_inherent_impl(mut impl_block: venial::Impl) -> ParseResult<Toke
         ::godot::sys::plugin_add!(__GODOT_PLUGIN_REGISTRY in #prv; #prv::ClassPlugin {
             class_name: #class_name_obj,
             item: #prv::PluginItem::InherentImpl {
+                docs: #docs,
                 register_methods_constants_fn: #prv::ErasedRegisterFn {
                     raw: #prv::callbacks::register_user_methods_constants::<#class_name>,
                 },

godot-macros/src/class/data_models/interface_trait_impl.rs

@@ -42,7 +42,10 @@ pub fn transform_trait_impl(original_impl: venial::Impl) -> ParseResult<TokenStr
     let mut virtual_method_names = vec![];
 
     let prv = quote! { ::godot::private };
-
+    #[cfg(feature = "docs")]
+    let docs = crate::docs::make_virtual_impl_docs(&original_impl.body_items);
+    #[cfg(not(feature = "docs"))]
+    let docs = "";
     for item in original_impl.body_items.iter() {
         let method = if let venial::ImplMember::AssocFunction(f) = item {
             f
@@ -388,6 +391,7 @@ pub fn transform_trait_impl(original_impl: venial::Impl) -> ParseResult<TokenStr
         ::godot::sys::plugin_add!(__GODOT_PLUGIN_REGISTRY in #prv; #prv::ClassPlugin {
             class_name: #class_name_obj,
             item: #prv::PluginItem::ITraitImpl {
+                docs: #docs,
                 user_register_fn: #register_fn,
                 user_create_fn: #create_fn,
                 user_recreate_fn: #recreate_fn,

godot-macros/src/class/data_models/signal.rs

@@ -10,6 +10,7 @@ use proc_macro2::TokenStream;
 use quote::quote;
 
 /// Holds information known from a signal's definition
+#[derive(Clone)]
 pub struct SignalDefinition {
     /// The signal's function signature.
     pub signature: venial::Function,

godot-macros/src/class/derive_godot_class.rs

@@ -74,7 +74,7 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
 
     match struct_cfg.init_strategy {
         InitStrategy::Generated => {
-            godot_init_impl = make_godot_init_impl(class_name, fields);
+            godot_init_impl = make_godot_init_impl(class_name, &fields);
             create_fn = quote! { Some(#prv::callbacks::create::<#class_name>) };
 
             if cfg!(since_api = "4.2") {
@@ -104,6 +104,14 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
     };
 
     let is_tool = struct_cfg.is_tool;
+    #[cfg(feature = "docs")]
+    let docs = crate::docs::make_definition_docs(
+        base_class.to_string(),
+        class.attributes.clone(),
+        fields.all_fields,
+    );
+    #[cfg(not(feature = "docs"))]
+    let docs = quote! { [""; 3] };
 
     Ok(quote! {
         impl ::godot::obj::GodotClass for #class_name {
@@ -129,6 +137,7 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
         ::godot::sys::plugin_add!(__GODOT_PLUGIN_REGISTRY in #prv; #prv::ClassPlugin {
             class_name: #class_name_obj,
             item: #prv::PluginItem::Struct {
+                docs: #docs,
                 base_class_name: #base_class_name_obj,
                 generated_create_fn: #create_fn,
                 generated_recreate_fn: #recreate_fn,
@@ -192,17 +201,18 @@ struct ClassAttributes {
     rename: Option<Ident>,
 }
 
-fn make_godot_init_impl(class_name: &Ident, fields: Fields) -> TokenStream {
-    let base_init = if let Some(Field { name, .. }) = fields.base_field {
+fn make_godot_init_impl(class_name: &Ident, fields: &Fields) -> TokenStream {
+    let base_init = if let Some(Field { name, .. }) = &fields.base_field {
         quote! { #name: base, }
     } else {
         TokenStream::new()
     };
 
-    let rest_init = fields.all_fields.into_iter().map(|field| {
-        let field_name = field.name;
+    let rest_init = fields.all_fields.iter().map(|field| {
+        let field_name = field.name.clone();
         let value_expr = field
             .default
+            .clone()
             .unwrap_or_else(|| quote! { ::std::default::Default::default() });
 
         quote! { #field_name: #value_expr, }