Merge pull request #79239 from raulsntos/dotnet/document-generated-members

C#: Document generated members

modules/mono/editor/Godot.NET.Sdk/Godot.SourceGenerators/ScriptMethodsGenerator.cs

@@ -135,6 +135,10 @@ namespace Godot.SourceGenerators
 
             source.Append("#pragma warning disable CS0109 // Disable warning about redundant 'new' keyword\n");
 
+            source.Append("    /// <summary>\n")
+                .Append("    /// Cached StringNames for the methods contained in this class, for fast lookup.\n")
+                .Append("    /// </summary>\n");
+
             source.Append(
                 $"    public new class MethodName : {symbol.BaseType.FullQualifiedNameIncludeGlobal()}.MethodName {{\n");
 
@@ -147,6 +151,12 @@ namespace Godot.SourceGenerators
 
             foreach (string methodName in distinctMethodNames)
             {
+                source.Append("        /// <summary>\n")
+                    .Append("        /// Cached name for the '")
+                    .Append(methodName)
+                    .Append("' method.\n")
+                    .Append("        /// </summary>\n");
+
                 source.Append("        public new static readonly global::Godot.StringName ");
                 source.Append(methodName);
                 source.Append(" = \"");
@@ -162,6 +172,14 @@ namespace Godot.SourceGenerators
             {
                 const string listType = "global::System.Collections.Generic.List<global::Godot.Bridge.MethodInfo>";
 
+                source.Append("    /// <summary>\n")
+                    .Append("    /// Get the method information for all the methods declared in this class.\n")
+                    .Append("    /// This method is used by Godot to register the available methods in the editor.\n")
+                    .Append("    /// Do not call this method.\n")
+                    .Append("    /// </summary>\n");
+
+                source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
+
                 source.Append("    internal new static ")
                     .Append(listType)
                     .Append(" GetGodotMethodList()\n    {\n");
@@ -188,6 +206,8 @@ namespace Godot.SourceGenerators
 
             if (godotClassMethods.Length > 0)
             {
+                source.Append("    /// <inheritdoc/>\n");
+                source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
                 source.Append("    protected override bool InvokeGodotClassMethod(in godot_string_name method, ");
                 source.Append("NativeVariantPtrArgs args, out godot_variant ret)\n    {\n");
 
@@ -205,6 +225,8 @@ namespace Godot.SourceGenerators
 
             if (distinctMethodNames.Length > 0)
             {
+                source.Append("    /// <inheritdoc/>\n");
+                source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
                 source.Append("    protected override bool HasGodotClassMethod(in godot_string_name method)\n    {\n");
 
                 bool isFirstEntry = true;

modules/mono/editor/Godot.NET.Sdk/Godot.SourceGenerators/ScriptPropertiesGenerator.cs

@@ -124,6 +124,10 @@ namespace Godot.SourceGenerators
 
             source.Append("#pragma warning disable CS0109 // Disable warning about redundant 'new' keyword\n");
 
+            source.Append("    /// <summary>\n")
+                .Append("    /// Cached StringNames for the properties and fields contained in this class, for fast lookup.\n")
+                .Append("    /// </summary>\n");
+
             source.Append(
                 $"    public new class PropertyName : {symbol.BaseType.FullQualifiedNameIncludeGlobal()}.PropertyName {{\n");
 
@@ -132,6 +136,13 @@ namespace Godot.SourceGenerators
             foreach (var property in godotClassProperties)
             {
                 string propertyName = property.PropertySymbol.Name;
+
+                source.Append("        /// <summary>\n")
+                    .Append("        /// Cached name for the '")
+                    .Append(propertyName)
+                    .Append("' property.\n")
+                    .Append("        /// </summary>\n");
+
                 source.Append("        public new static readonly global::Godot.StringName ");
                 source.Append(propertyName);
                 source.Append(" = \"");
@@ -142,6 +153,13 @@ namespace Godot.SourceGenerators
             foreach (var field in godotClassFields)
             {
                 string fieldName = field.FieldSymbol.Name;
+
+                source.Append("        /// <summary>\n")
+                    .Append("        /// Cached name for the '")
+                    .Append(fieldName)
+                    .Append("' field.\n")
+                    .Append("        /// </summary>\n");
+
                 source.Append("        public new static readonly global::Godot.StringName ");
                 source.Append(fieldName);
                 source.Append(" = \"");
@@ -162,6 +180,8 @@ namespace Godot.SourceGenerators
 
                 if (!allPropertiesAreReadOnly)
                 {
+                    source.Append("    /// <inheritdoc/>\n");
+                    source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
                     source.Append("    protected override bool SetGodotClassPropertyValue(in godot_string_name name, ");
                     source.Append("in godot_variant value)\n    {\n");
 
@@ -193,6 +213,8 @@ namespace Godot.SourceGenerators
 
                 // Generate GetGodotClassPropertyValue
 
+                source.Append("    /// <inheritdoc/>\n");
+                source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
                 source.Append("    protected override bool GetGodotClassPropertyValue(in godot_string_name name, ");
                 source.Append("out godot_variant value)\n    {\n");
 
@@ -217,7 +239,15 @@ namespace Godot.SourceGenerators
 
                 // Generate GetGodotPropertyList
 
-                string dictionaryType = "global::System.Collections.Generic.List<global::Godot.Bridge.PropertyInfo>";
+                const string dictionaryType = "global::System.Collections.Generic.List<global::Godot.Bridge.PropertyInfo>";
+
+                source.Append("    /// <summary>\n")
+                    .Append("    /// Get the property information for all the properties declared in this class.\n")
+                    .Append("    /// This method is used by Godot to register the available properties in the editor.\n")
+                    .Append("    /// Do not call this method.\n")
+                    .Append("    /// </summary>\n");
+
+                source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
 
                 source.Append("    internal new static ")
                     .Append(dictionaryType)

modules/mono/editor/Godot.NET.Sdk/Godot.SourceGenerators/ScriptPropertyDefValGenerator.cs

@@ -285,10 +285,20 @@ namespace Godot.SourceGenerators
             {
                 source.Append("#pragma warning disable CS0109 // Disable warning about redundant 'new' keyword\n");
 
-                string dictionaryType =
+                const string dictionaryType =
                     "global::System.Collections.Generic.Dictionary<global::Godot.StringName, global::Godot.Variant>";
 
                 source.Append("#if TOOLS\n");
+
+                source.Append("    /// <summary>\n")
+                    .Append("    /// Get the default values for all properties declared in this class.\n")
+                    .Append("    /// This method is used by Godot to determine the value that will be\n")
+                    .Append("    /// used by the inspector when resetting properties.\n")
+                    .Append("    /// Do not call this method.\n")
+                    .Append("    /// </summary>\n");
+
+                source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
+
                 source.Append("    internal new static ");
                 source.Append(dictionaryType);
                 source.Append(" GetGodotPropertyDefaultValues()\n    {\n");
@@ -320,7 +330,8 @@ namespace Godot.SourceGenerators
 
                 source.Append("        return values;\n");
                 source.Append("    }\n");
-                source.Append("#endif\n");
+
+                source.Append("#endif // TOOLS\n");
 
                 source.Append("#pragma warning restore CS0109\n");
             }

modules/mono/editor/Godot.NET.Sdk/Godot.SourceGenerators/ScriptSerializationGenerator.cs

@@ -149,6 +149,8 @@ namespace Godot.SourceGenerators
                 godotSignalDelegates.Add(new(signalName, signalDelegateSymbol, invokeMethodData.Value));
             }
 
+            source.Append("    /// <inheritdoc/>\n");
+            source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
             source.Append(
                 "    protected override void SaveGodotObjectData(global::Godot.Bridge.GodotSerializationInfo info)\n    {\n");
             source.Append("        base.SaveGodotObjectData(info);\n");
@@ -196,6 +198,8 @@ namespace Godot.SourceGenerators
 
             source.Append("    }\n");
 
+            source.Append("    /// <inheritdoc/>\n");
+            source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
             source.Append(
                 "    protected override void RestoreGodotObjectData(global::Godot.Bridge.GodotSerializationInfo info)\n    {\n");
             source.Append("        base.RestoreGodotObjectData(info);\n");

modules/mono/editor/Godot.NET.Sdk/Godot.SourceGenerators/ScriptSignalsGenerator.cs

@@ -176,6 +176,10 @@ namespace Godot.SourceGenerators
 
             source.Append("#pragma warning disable CS0109 // Disable warning about redundant 'new' keyword\n");
 
+            source.Append("    /// <summary>\n")
+                .Append("    /// Cached StringNames for the signals contained in this class, for fast lookup.\n")
+                .Append("    /// </summary>\n");
+
             source.Append(
                 $"    public new class SignalName : {symbol.BaseType.FullQualifiedNameIncludeGlobal()}.SignalName {{\n");
 
@@ -184,6 +188,13 @@ namespace Godot.SourceGenerators
             foreach (var signalDelegate in godotSignalDelegates)
             {
                 string signalName = signalDelegate.Name;
+
+                source.Append("        /// <summary>\n")
+                    .Append("        /// Cached name for the '")
+                    .Append(signalName)
+                    .Append("' signal.\n")
+                    .Append("        /// </summary>\n");
+
                 source.Append("        public new static readonly global::Godot.StringName ");
                 source.Append(signalName);
                 source.Append(" = \"");
@@ -199,6 +210,14 @@ namespace Godot.SourceGenerators
             {
                 const string listType = "global::System.Collections.Generic.List<global::Godot.Bridge.MethodInfo>";
 
+                source.Append("    /// <summary>\n")
+                    .Append("    /// Get the signal information for all the signals declared in this class.\n")
+                    .Append("    /// This method is used by Godot to register the available signals in the editor.\n")
+                    .Append("    /// Do not call this method.\n")
+                    .Append("    /// </summary>\n");
+
+                source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
+
                 source.Append("    internal new static ")
                     .Append(listType)
                     .Append(" GetGodotSignalList()\n    {\n");
@@ -258,6 +277,8 @@ namespace Godot.SourceGenerators
 
             if (godotSignalDelegates.Count > 0)
             {
+                source.Append("    /// <inheritdoc/>\n");
+                source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
                 source.Append(
                     "    protected override void RaiseGodotClassSignalCallbacks(in godot_string_name signal, ");
                 source.Append("NativeVariantPtrArgs args)\n    {\n");
@@ -276,6 +297,8 @@ namespace Godot.SourceGenerators
 
             if (godotSignalDelegates.Count > 0)
             {
+                source.Append("    /// <inheritdoc/>\n");
+                source.Append("    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]\n");
                 source.Append(
                     "    protected override bool HasGodotClassSignal(in godot_string_name signal)\n    {\n");
 

modules/mono/editor/bindings_generator.cpp

@@ -1616,7 +1616,16 @@ Error BindingsGenerator::_generate_cs_type(const TypeInterface &itype, const Str
 
 		// Generate InvokeGodotClassMethod
 
-		output << MEMBER_BEGIN "protected internal " << (is_derived_type ? "override" : "virtual")
+		output << MEMBER_BEGIN "/// <summary>\n"
+			   << INDENT1 "/// Invokes the method with the given name, using the given arguments.\n"
+			   << INDENT1 "/// This method is used by Godot to invoke methods from the engine side.\n"
+			   << INDENT1 "/// Do not call or override this method.\n"
+			   << INDENT1 "/// </summary>\n"
+			   << INDENT1 "/// <param name=\"method\">Name of the method to invoke.</param>\n"
+			   << INDENT1 "/// <param name=\"args\">Arguments to use with the invoked method.</param>\n"
+			   << INDENT1 "/// <param name=\"ret\">Value returned by the invoked method.</param>\n";
+
+		output << INDENT1 "protected internal " << (is_derived_type ? "override" : "virtual")
 			   << " bool " CS_METHOD_INVOKE_GODOT_CLASS_METHOD "(in godot_string_name method, "
 			   << "NativeVariantPtrArgs args, out godot_variant ret)\n"
 			   << INDENT1 "{\n";
@@ -1696,6 +1705,13 @@ Error BindingsGenerator::_generate_cs_type(const TypeInterface &itype, const Str
 
 		// Generate HasGodotClassMethod
 
+		output << MEMBER_BEGIN "/// <summary>\n"
+			   << INDENT1 "/// Check if the type contains a method with the given name.\n"
+			   << INDENT1 "/// This method is used by Godot to check if a method exists before invoking it.\n"
+			   << INDENT1 "/// Do not call or override this method.\n"
+			   << INDENT1 "/// </summary>\n"
+			   << INDENT1 "/// <param name=\"method\">Name of the method to check for.</param>\n";
+
 		output << MEMBER_BEGIN "protected internal " << (is_derived_type ? "override" : "virtual")
 			   << " bool " CS_METHOD_HAS_GODOT_CLASS_METHOD "(in godot_string_name method)\n"
 			   << INDENT1 "{\n";
@@ -1728,6 +1744,13 @@ Error BindingsGenerator::_generate_cs_type(const TypeInterface &itype, const Str
 
 		// Generate HasGodotClassSignal
 
+		output << MEMBER_BEGIN "/// <summary>\n"
+			   << INDENT1 "/// Check if the type contains a signal with the given name.\n"
+			   << INDENT1 "/// This method is used by Godot to check if a signal exists before raising it.\n"
+			   << INDENT1 "/// Do not call or override this method.\n"
+			   << INDENT1 "/// </summary>\n"
+			   << INDENT1 "/// <param name=\"method\">Name of the method to check for.</param>\n";
+
 		output << MEMBER_BEGIN "protected internal " << (is_derived_type ? "override" : "virtual")
 			   << " bool " CS_METHOD_HAS_GODOT_CLASS_SIGNAL "(in godot_string_name signal)\n"
 			   << INDENT1 "{\n";
@@ -1758,39 +1781,57 @@ Error BindingsGenerator::_generate_cs_type(const TypeInterface &itype, const Str
 	//Generate StringName for all class members
 	bool is_inherit = !itype.is_singleton && obj_types.has(itype.base_name);
 	//PropertyName
+	output << MEMBER_BEGIN "/// <summary>\n"
+		   << INDENT1 "/// Cached StringNames for the properties and fields contained in this class, for fast lookup.\n"
+		   << INDENT1 "/// </summary>\n";
 	if (is_inherit) {
-		output << MEMBER_BEGIN "public new class PropertyName : " << obj_types[itype.base_name].proxy_name << ".PropertyName";
+		output << INDENT1 "public new class PropertyName : " << obj_types[itype.base_name].proxy_name << ".PropertyName";
 	} else {
-		output << MEMBER_BEGIN "public class PropertyName";
+		output << INDENT1 "public class PropertyName";
 	}
 	output << "\n"
 		   << INDENT1 "{\n";
 	for (const PropertyInterface &iprop : itype.properties) {
-		output << INDENT2 "public static readonly StringName " << iprop.proxy_name << " = \"" << iprop.cname << "\";\n";
+		output << INDENT2 "/// <summary>\n"
+			   << INDENT2 "/// Cached name for the '" << iprop.cname << "' property.\n"
+			   << INDENT2 "/// </summary>\n"
+			   << INDENT2 "public static readonly StringName " << iprop.proxy_name << " = \"" << iprop.cname << "\";\n";
 	}
 	output << INDENT1 "}\n";
 	//MethodName
+	output << MEMBER_BEGIN "/// <summary>\n"
+		   << INDENT1 "/// Cached StringNames for the methods contained in this class, for fast lookup.\n"
+		   << INDENT1 "/// </summary>\n";
 	if (is_inherit) {
-		output << MEMBER_BEGIN "public new class MethodName : " << obj_types[itype.base_name].proxy_name << ".MethodName";
+		output << INDENT1 "public new class MethodName : " << obj_types[itype.base_name].proxy_name << ".MethodName";
 	} else {
-		output << MEMBER_BEGIN "public class MethodName";
+		output << INDENT1 "public class MethodName";
 	}
 	output << "\n"
 		   << INDENT1 "{\n";
 	for (const MethodInterface &imethod : itype.methods) {
-		output << INDENT2 "public static readonly StringName " << imethod.proxy_name << " = \"" << imethod.cname << "\";\n";
+		output << INDENT2 "/// <summary>\n"
+			   << INDENT2 "/// Cached name for the '" << imethod.cname << "' method.\n"
+			   << INDENT2 "/// </summary>\n"
+			   << INDENT2 "public static readonly StringName " << imethod.proxy_name << " = \"" << imethod.cname << "\";\n";
 	}
 	output << INDENT1 "}\n";
 	//SignalName
+	output << MEMBER_BEGIN "/// <summary>\n"
+		   << INDENT1 "/// Cached StringNames for the signals contained in this class, for fast lookup.\n"
+		   << INDENT1 "/// </summary>\n";
 	if (is_inherit) {
-		output << MEMBER_BEGIN "public new class SignalName : " << obj_types[itype.base_name].proxy_name << ".SignalName";
+		output << INDENT1 "public new class SignalName : " << obj_types[itype.base_name].proxy_name << ".SignalName";
 	} else {
-		output << MEMBER_BEGIN "public class SignalName";
+		output << INDENT1 "public class SignalName";
 	}
 	output << "\n"
 		   << INDENT1 "{\n";
 	for (const SignalInterface &isignal : itype.signals_) {
-		output << INDENT2 "public static readonly StringName " << isignal.proxy_name << " = \"" << isignal.cname << "\";\n";
+		output << INDENT2 "/// <summary>\n"
+			   << INDENT2 "/// Cached name for the '" << isignal.cname << "' signal.\n"
+			   << INDENT2 "/// </summary>\n"
+			   << INDENT2 "public static readonly StringName " << isignal.proxy_name << " = \"" << isignal.cname << "\";\n";
 	}
 	output << INDENT1 "}\n";
 

modules/mono/glue/GodotSharp/GodotSharp/Core/GodotObject.base.cs

@@ -191,12 +191,30 @@ namespace Godot
         }
 
         // ReSharper disable once VirtualMemberNeverOverridden.Global
+        /// <summary>
+        /// Set the value of a property contained in this class.
+        /// This method is used by Godot to assign property values.
+        /// Do not call or override this method.
+        /// </summary>
+        /// <param name="name">Name of the property to set.</param>
+        /// <param name="value">Value to set the property to if it was found.</param>
+        /// <returns><see langword="true"/> if a property with the given name was found.</returns>
+        [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]
         protected internal virtual bool SetGodotClassPropertyValue(in godot_string_name name, in godot_variant value)
         {
             return false;
         }
 
         // ReSharper disable once VirtualMemberNeverOverridden.Global
+        /// <summary>
+        /// Get the value of a property contained in this class.
+        /// This method is used by Godot to retrieve property values.
+        /// Do not call or override this method.
+        /// </summary>
+        /// <param name="name">Name of the property to get.</param>
+        /// <param name="value">Value of the property if it was found.</param>
+        /// <returns><see langword="true"/> if a property with the given name was found.</returns>
+        [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]
         protected internal virtual bool GetGodotClassPropertyValue(in godot_string_name name, out godot_variant value)
         {
             value = default;
@@ -204,6 +222,14 @@ namespace Godot
         }
 
         // ReSharper disable once VirtualMemberNeverOverridden.Global
+        /// <summary>
+        /// Raises the signal with the given name, using the given arguments.
+        /// This method is used by Godot to raise signals from the engine side.\n"
+        /// Do not call or override this method.
+        /// </summary>
+        /// <param name="signal">Name of the signal to raise.</param>
+        /// <param name="args">Arguments to use with the raised signal.</param>
+        [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]
         protected internal virtual void RaiseGodotClassSignalCallbacks(in godot_string_name signal,
             NativeVariantPtrArgs args)
         {
@@ -233,11 +259,25 @@ namespace Godot
             return nativeConstructor;
         }
 
+        /// <summary>
+        /// Saves this instance's state to be restored when reloading assemblies.
+        /// Do not call or override this method.
+        /// To add data to be saved and restored, implement <see cref="ISerializationListener"/>.
+        /// </summary>
+        /// <param name="info">Object used to save the data.</param>
+        [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]
         protected internal virtual void SaveGodotObjectData(GodotSerializationInfo info)
         {
         }
 
         // TODO: Should this be a constructor overload?
+        /// <summary>
+        /// Restores this instance's state after reloading assemblies.
+        /// Do not call or override this method.
+        /// To add data to be saved and restored, implement <see cref="ISerializationListener"/>.
+        /// </summary>
+        /// <param name="info">Object that contains the previously saved data.</param>
+        [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]
         protected internal virtual void RestoreGodotObjectData(GodotSerializationInfo info)
         {
         }

modules/mono/glue/GodotSharp/GodotSharp/Core/Interfaces/ISerializationListener.cs

@@ -1,11 +1,21 @@
 namespace Godot
 {
     /// <summary>
-    /// An interface that requires methods for before and after serialization.
+    /// Allows a GodotObject to react to the serialization/deserialization
+    /// that occurs when Godot reloads assemblies.
     /// </summary>
     public interface ISerializationListener
     {
+        /// <summary>
+        /// Executed before serializing this instance's state when reloading assemblies.
+        /// Clear any data that should not be serialized.
+        /// </summary>
         void OnBeforeSerialize();
+
+        /// <summary>
+        /// Executed after deserializing this instance's state after reloading assemblies.
+        /// Restore any state that has been lost.
+        /// </summary>
         void OnAfterDeserialize();
     }
 }