Add a note about C# differences in classref doc

godotengine · Jul 8, 2023 · a164e3e · a164e3e
1 parent c3b0a92
commit a164e3e
Show file tree

Hide file tree

Showing 2 changed files with 97 additions and 0 deletions.
diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py
@@ -66,6 +66,15 @@
     "This method doesn't need an instance to be called, so it can be called directly using the class name.",
     "This method describes a valid operator to use with this type as left-hand operand.",
     "This value is an integer composed as a bitmask of the following flags.",
+    "There is currently no description for this class. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
+    "There is currently no description for this signal. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
+    "There is currently no description for this annotation. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
+    "There is currently no description for this property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
+    "There is currently no description for this constructor. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
+    "There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
+    "There is currently no description for this operator. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
+    "There is currently no description for this theme property. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!",
+    "There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information.",
 ]
 strings_l10n: Dict[str, str] = {}
 
@@ -92,6 +101,36 @@
     "ScriptEditor",
     "ScriptEditorBase",
 ]
+# Sync with the types mentioned in https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/c_sharp_differences.html
+CLASSES_WITH_CSHARP_DIFFERENCES: List[str] = [
+    "@GlobalScope",
+    "String",
+    "NodePath",
+    "Signal",
+    "Callable",
+    "RID",
+    "Basis",
+    "Transform2D",
+    "Transform3D",
+    "Rect2",
+    "Rect2i",
+    "AABB",
+    "Quaternion",
+    "Projection",
+    "Color",
+    "Array",
+    "Dictionary",
+    "PackedByteArray",
+    "PackedColorArray",
+    "PackedFloat32Array",
+    "PackedFloat64Array",
+    "PackedInt32Array",
+    "PackedInt64Array",
+    "PackedStringArray",
+    "PackedVector2Array",
+    "PackedVector3Array",
+    "Variant",
+]
 
 
 class State:
@@ -842,6 +881,15 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
             + "\n\n"
         )
 
+    if class_def.name in CLASSES_WITH_CSHARP_DIFFERENCES:
+        f.write(".. note::\n\n\t")
+        f.write(
+            translate(
+                "There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information."
+            )
+            + "\n\n"
+        )
+
     # Online tutorials
     if len(class_def.tutorials) > 0:
         f.write(".. rst-class:: classref-introduction-group\n\n")

diff --git a/editor/editor_help.cpp b/editor/editor_help.cpp
@@ -45,6 +45,39 @@
 
 #define CONTRIBUTE_URL vformat("%s/contributing/documentation/updating_the_class_reference.html", VERSION_DOCS_URL)
 
+#ifdef MODULE_MONO_ENABLED
+// Sync with the types mentioned in https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/c_sharp_differences.html
+const Vector<String> classes_with_csharp_differences = {
+	"@GlobalScope",
+	"String",
+	"NodePath",
+	"Signal",
+	"Callable",
+	"RID",
+	"Basis",
+	"Transform2D",
+	"Transform3D",
+	"Rect2",
+	"Rect2i",
+	"AABB",
+	"Quaternion",
+	"Projection",
+	"Color",
+	"Array",
+	"Dictionary",
+	"PackedByteArray",
+	"PackedColorArray",
+	"PackedFloat32Array",
+	"PackedFloat64Array",
+	"PackedInt32Array",
+	"PackedInt64Array",
+	"PackedStringArray",
+	"PackedVector2Array",
+	"PackedVector3Array",
+	"Variant",
+};
+#endif
+
 // TODO: this is sometimes used directly as doc->something, other times as EditorHelp::get_doc_data(), which is thread-safe.
 // Might this be a problem?
 DocTools *EditorHelp::doc = nullptr;
@@ -888,10 +921,26 @@ void EditorHelp::_update_doc() {
 			class_desc->append_text(TTR("There is currently no description for this class. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
 		}
 
+		class_desc->add_newline();
+		class_desc->add_newline();
+	}
+
+#ifdef MODULE_MONO_ENABLED
+	if (classes_with_csharp_differences.has(cd.name)) {
+		const String &csharp_differences_url = vformat("%s/tutorials/scripting/c_sharp/c_sharp_differences.html", VERSION_DOCS_URL);
+
+		class_desc->push_color(theme_cache.text_color);
+		_push_normal_font();
+		class_desc->push_indent(1);
+		_add_text("[b]" + TTR("Note:") + "[/b] " + vformat(TTR("There are notable differences when using this API with C#. See [url=%s]C# API differences to GDScript[/url] for more information."), csharp_differences_url));
 		class_desc->pop();
+		_pop_normal_font();
+		class_desc->pop();
+
 		class_desc->add_newline();
 		class_desc->add_newline();
 	}
+#endif
 
 	// Online tutorials
 	if (cd.tutorials.size()) {