From a164e3e7b34f0f3667b153ee0c7784a76e64dd54 Mon Sep 17 00:00:00 2001 From: Raul Santos Date: Sat, 8 Jul 2023 13:17:41 +0200 Subject: [PATCH] Add a note about C# differences in classref doc --- doc/tools/make_rst.py | 48 +++++++++++++++++++++++++++++++++++++++ editor/editor_help.cpp | 51 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 98 insertions(+), 1 deletion(-) diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index 28d30a594de..54bad7cf05b 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -66,6 +66,15 @@ BASE_STRINGS = [ "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 `!", + "There is currently no description for this signal. Please help us by :ref:`contributing one `!", + "There is currently no description for this annotation. Please help us by :ref:`contributing one `!", + "There is currently no description for this property. Please help us by :ref:`contributing one `!", + "There is currently no description for this constructor. Please help us by :ref:`contributing one `!", + "There is currently no description for this method. Please help us by :ref:`contributing one `!", + "There is currently no description for this operator. Please help us by :ref:`contributing one `!", + "There is currently no description for this theme property. Please help us by :ref:`contributing one `!", + "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 @@ EDITOR_CLASSES: List[str] = [ "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 index 5a3841e4ca7..d29a2828140 100644 --- 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 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,11 +921,27 @@ 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->pop(); 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()) { _push_title_font();