C#: Documentation on supporting C# scripts in the Godot editor.

Co-authored-by: DE YU <[email protected]>
Co-authored-by: Magian <[email protected]>

Author: magian1127

editor/file_system/editor_file_system.cpp

@@ -2274,6 +2274,10 @@ bool EditorFileSystem::_should_reload_script(const String &p_path) {
 		return false;
 	}
 
+	if (scr->get_language()->get_name() == "C#") {
+		return false;
+	}
+
 	// Scripts are reloaded via the script editor if they are currently opened.
 	if (ScriptEditor::get_singleton()->get_open_scripts().has(scr)) {
 		return false;

editor/scene/connections_dialog.cpp

@@ -1496,7 +1496,6 @@ void ConnectionsDock::update_tree() {
 	}
 
 	TreeItem *root = tree->create_item();
-	DocTools *doc_data = EditorHelp::get_doc_data();
 	EditorData &editor_data = EditorNode::get_editor_data();
 	StringName native_base = selected_node->get_class();
 	Ref<Script> script_base = selected_node->get_script();
@@ -1513,12 +1512,12 @@ void ConnectionsDock::update_tree() {
 				class_name = script_base->get_path().get_file();
 			}
 
-			doc_class_name = script_base->get_global_name();
+			doc_class_name = script_base->get_doc_class_name();
 			if (doc_class_name.is_empty()) {
-				doc_class_name = script_base->get_path().trim_prefix("res://").quote();
-			}
-			if (!doc_class_name.is_empty() && !doc_data->class_list.find(doc_class_name)) {
-				doc_class_name = String();
+				doc_class_name = script_base->get_global_name();
+				if (doc_class_name.is_empty()) {
+					doc_class_name = script_base->get_path().trim_prefix("res://").quote();
+				}
 			}
 
 			class_icon = editor_data.get_script_icon(script_base->get_path());
@@ -1551,10 +1550,6 @@ void ConnectionsDock::update_tree() {
 			class_name = native_base;
 			doc_class_name = native_base;
 
-			if (!doc_data->class_list.find(doc_class_name)) {
-				doc_class_name = String();
-			}
-
 			if (has_theme_icon(native_base, EditorStringName(EditorIcons))) {
 				class_icon = get_editor_theme_icon(native_base);
 			}

modules/mono/csharp_script.cpp

@@ -1044,6 +1044,10 @@ Error CSharpLanguage::open_in_external_editor(const Ref<Script> &p_script, int p
 bool CSharpLanguage::overrides_external_editor() {
 	return get_godotsharp_editor()->call("OverridesExternalEditor");
 }
+
+bool CSharpLanguage::supports_documentation() const {
+	return true;
+}
 #endif
 
 bool CSharpLanguage::debug_break_parse(const String &p_file, int p_line, const String &p_error) {
@@ -2080,9 +2084,15 @@ void GD_CLR_STDCALL CSharpScript::_add_property_info_list_callback(CSharpScript
 	GDMonoCache::godotsharp_property_info *props = (GDMonoCache::godotsharp_property_info *)p_props;
 
 #ifdef TOOLS_ENABLED
-	p_script->exported_members_cache.push_back(PropertyInfo(
-			Variant::NIL, p_script->type_info.class_name, PROPERTY_HINT_NONE,
-			p_script->get_path(), PROPERTY_USAGE_CATEGORY));
+	if (p_script->get_path().is_empty()) {
+		p_script->exported_members_cache.push_back(PropertyInfo(
+				Variant::NIL, p_script->type_info.class_name, PROPERTY_HINT_NONE,
+				String("res://") + String(p_script->doc_class_name).lstrip("\"").rstrip("\""), PROPERTY_USAGE_CATEGORY));
+	} else {
+		p_script->exported_members_cache.push_back(PropertyInfo(
+				Variant::NIL, p_script->type_info.class_name, PROPERTY_HINT_NONE,
+				p_script->get_path(), PROPERTY_USAGE_CATEGORY));
+	}
 #endif
 
 	for (int i = 0; i < p_count; i++) {
@@ -2120,6 +2130,38 @@ void GD_CLR_STDCALL CSharpScript::_add_property_default_values_callback(CSharpSc
 		p_script->exported_members_defval_cache[name] = value;
 	}
 }
+
+void CSharpScript::get_docs(Ref<CSharpScript> p_script) {
+	Dictionary class_doc_dict;
+	class_doc_dict.~Dictionary();
+
+	GDMonoCache::managed_callbacks.ScriptManagerBridge_GetDocs(p_script.ptr(), &class_doc_dict);
+
+	p_script->docs.clear();
+
+	if (class_doc_dict.is_empty()) {
+		// Script has no docs.
+		return;
+	}
+
+	String inherits;
+	Ref<CSharpScript> base = p_script->get_base_script();
+	if (base.is_null()) {
+		// Must be a native base type.
+		inherits = p_script->get_instance_base_type();
+	} else {
+		inherits = base->get_global_name();
+		if (inherits == StringName()) {
+			inherits = base->get_path().trim_prefix("res://").quote();
+		}
+	}
+
+	DocData::ClassDoc class_doc = DocData::ClassDoc().from_dict(class_doc_dict);
+	class_doc.inherits = inherits;
+
+	p_script->doc_class_name = class_doc.name;
+	p_script->docs.append(class_doc);
+}
 #endif
 
 bool CSharpScript::_update_exports(PlaceHolderScriptInstance *p_instance_to_update) {
@@ -2344,6 +2386,10 @@ void CSharpScript::update_script_class_info(Ref<CSharpScript> p_script) {
 	}
 
 	p_script->base_script = base_script;
+
+#ifdef TOOLS_ENABLED
+	get_docs(p_script);
+#endif
 }
 
 bool CSharpScript::can_instantiate() const {

modules/mono/csharp_script.h

@@ -197,6 +197,8 @@ class CSharpScript : public Script {
 	bool exports_invalidated = true;
 	void _update_exports_values(HashMap<StringName, Variant> &values, List<PropertyInfo> &propnames);
 	void _placeholder_erased(PlaceHolderScriptInstance *p_placeholder) override;
+	StringName doc_class_name;
+	Vector<DocData::ClassDoc> docs;
 #endif
 
 #if defined(TOOLS_ENABLED) || defined(DEBUG_ENABLED)
@@ -210,6 +212,7 @@ class CSharpScript : public Script {
 	static void GD_CLR_STDCALL _add_property_info_list_callback(CSharpScript *p_script, const String *p_current_class_name, void *p_props, int32_t p_count);
 #ifdef TOOLS_ENABLED
 	static void GD_CLR_STDCALL _add_property_default_values_callback(CSharpScript *p_script, void *p_def_vals, int32_t p_count);
+	static void get_docs(Ref<CSharpScript> p_script);
 #endif
 	bool _update_exports(PlaceHolderScriptInstance *p_instance_to_update = nullptr);
 
@@ -242,10 +245,8 @@ class CSharpScript : public Script {
 	void set_source_code(const String &p_code) override;
 
 #ifdef TOOLS_ENABLED
-	virtual StringName get_doc_class_name() const override { return StringName(); } // TODO
+	virtual StringName get_doc_class_name() const override { return doc_class_name; }
 	virtual Vector<DocData::ClassDoc> get_documentation() const override {
-		// TODO
-		Vector<DocData::ClassDoc> docs;
 		return docs;
 	}
 	virtual String get_class_icon_path() const override {
@@ -572,6 +573,7 @@ class CSharpLanguage : public ScriptLanguage {
 #ifdef TOOLS_ENABLED
 	Error open_in_external_editor(const Ref<Script> &p_script, int p_line, int p_col) override;
 	bool overrides_external_editor() override;
+	virtual bool supports_documentation() const override;
 #endif
 
 	RBMap<Object *, CSharpScriptBinding>::Element *insert_script_binding(Object *p_object, const CSharpScriptBinding &p_script_binding);

modules/mono/editor/Godot.NET.Sdk/Godot.SourceGenerators.Sample/ClassDoc.cs

@@ -0,0 +1,30 @@
+namespace Godot.SourceGenerators.Sample;
+
+/// <summary>
+/// class description
+/// test
+/// </summary>
+public partial class ClassDoc : GodotObject
+{
+    /// <summary>
+    /// field description
+    /// test
+    /// </summary>
+    [Export]
+    private int _fieldDocTest = 1;
+
+    /// <summary>
+    /// property description
+    /// test
+    /// </summary>
+    [Export]
+    public int PropertyDocTest { get; set; }
+
+    /// <summary>
+    /// signal description
+    /// test
+    /// </summary>
+    /// <param name="num"></param>
+    [Signal]
+    public delegate void SignalDocTestEventHandler(int num);
+}

modules/mono/editor/Godot.NET.Sdk/Godot.SourceGenerators.Tests/ScriptDocsGeneratorTests.cs

@@ -0,0 +1,24 @@
+using Xunit;
+
+namespace Godot.SourceGenerators.Tests;
+
+public class ScriptDocsGeneratorTests
+{
+    [Fact]
+    public async void Docs()
+    {
+        await CSharpSourceGeneratorVerifier<ScriptDocsGenerator>.Verify(
+            "ClassDoc.cs",
+            "ClassDoc_ScriptDocs.generated.cs"
+        );
+    }
+
+    [Fact]
+    public async void AllDocs()
+    {
+        await CSharpSourceGeneratorVerifier<ScriptDocsGenerator>.Verify(
+            "ClassAllDoc.cs",
+            "ClassAllDoc_ScriptDocs.generated.cs"
+        );
+    }
+}

modules/mono/editor/Godot.NET.Sdk/Godot.SourceGenerators.Tests/TestData/GeneratedSources/ClassAllDoc_ScriptDocs.generated.cs

@@ -0,0 +1,31 @@
+partial class ClassAllDoc
+{
+#pragma warning disable CS0109 // Disable warning about redundant 'new' keyword
+#if TOOLS
+    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]
+    internal new static global::Godot.Collections.Dictionary GetGodotClassDocs()
+    {
+        var docs = new global::Godot.Collections.Dictionary();
+        docs.Add("name","\"ClassAllDoc.cs\"");
+        docs.Add("brief_description",@"class description test");
+        docs.Add("description",@"class description test");
+
+        var propertyDocs = new global::Godot.Collections.Array();
+        propertyDocs.Add(new global::Godot.Collections.Dictionary { { "name", PropertyName.PropertyDocTest }, { @"type", @"int" }, { "description", @"property description test [code]ClassAllDoc[/code]" }});
+        propertyDocs.Add(new global::Godot.Collections.Dictionary { { "name", PropertyName._fieldDocTest }, { @"type", @"int" }, { "description", @"field description [code]true[/code] test [code]ClassAllDoc[/code]" }});
+        docs.Add("properties", propertyDocs);
+
+        var signalDocs  = new global::Godot.Collections.Array();
+        signalDocs.Add(new global::Godot.Collections.Dictionary { { "name", SignalName.SignalDocTest }, { "description", @"signal description ~!@#$%^*()_+{}| test [code]ClassAllDoc[/code][br][br][b]Parameters:[/b][br] • [b]num[/b]:" }});
+        docs.Add("signals", signalDocs);
+
+        docs.Add("is_script_doc", true);
+
+        docs.Add("script_path", "ClassAllDoc.cs");
+
+        return docs;
+    }
+
+#endif // TOOLS
+#pragma warning restore CS0109
+}

modules/mono/editor/Godot.NET.Sdk/Godot.SourceGenerators.Tests/TestData/GeneratedSources/ClassDoc_ScriptDocs.generated.cs

@@ -0,0 +1,26 @@
+partial class ClassDoc
+{
+#pragma warning disable CS0109 // Disable warning about redundant 'new' keyword
+#if TOOLS
+    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]
+    internal new static global::Godot.Collections.Dictionary GetGodotClassDocs()
+    {
+        var docs = new global::Godot.Collections.Dictionary();
+        docs.Add("name","\"ClassDoc.cs\"");
+        docs.Add("brief_description",@"This is the class documentation.");
+        docs.Add("description",@"This is the class documentation.");
+
+        var propertyDocs = new global::Godot.Collections.Array();
+        propertyDocs.Add(new global::Godot.Collections.Dictionary { { "name", PropertyName.MyProperty }, { @"type", @"int" }, { "description", @"There is currently no description for this property." }});
+        docs.Add("properties", propertyDocs);
+
+        docs.Add("is_script_doc", true);
+
+        docs.Add("script_path", "ClassDoc.cs");
+
+        return docs;
+    }
+
+#endif // TOOLS
+#pragma warning restore CS0109
+}

modules/mono/editor/Godot.NET.Sdk/Godot.SourceGenerators.Tests/TestData/Sources/ClassAllDoc.cs

@@ -0,0 +1,30 @@
+using Godot;
+
+/// <summary>
+/// class description
+/// test
+/// </summary>
+public partial class ClassAllDoc : GodotObject
+{
+    /// <summary>
+    /// field description <c>true</c>
+    /// test <see cref="ClassAllDoc"/>
+    /// </summary>
+    [Export]
+    private int _fieldDocTest = 1;
+
+    /// <summary>
+    /// property description
+    /// test <see cref="ClassAllDoc"/>
+    /// </summary>
+    [Export]
+    public int PropertyDocTest { get; set; }
+
+    /// <summary>
+    /// signal description ~!@#$%^*()_+{}|
+    /// test <see cref="ClassAllDoc"/>
+    /// </summary>
+    /// <param name="num"></param>
+    [Signal]
+    public delegate void SignalDocTestEventHandler(int num);
+}

modules/mono/editor/Godot.NET.Sdk/Godot.SourceGenerators.Tests/TestData/Sources/ClassDoc.cs

@@ -0,0 +1,10 @@
+using Godot;
+
+/// <summary>
+/// This is the class documentation.
+/// </summary>
+public partial class ClassDoc : GodotObject
+{
+    [Export]
+    public int MyProperty { get; set; }
+}