feat: replaced @bind.help/experimental/deprecated with standard JS comments and JSDoc like annotations

.changeset/silent-clouds-matter.md

@@ -0,0 +1,43 @@
+---
+"@godot-js/editor": minor
+---
+
+feat: additionally to @bind.help/experimental/deprecated add an editor setting to enable standard JS comments and JSDoc like annotations for documentation comments.
+
+You need to enable the setting, set ``Editor -> Editor Settings -> GodotJS -> Experimental -> Jsdoc Documentation Comments `` to ``on``.
+
+Here is an example for more information see https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_documentation_comments.html:
+````ts
+/**
+ * A brief description of the class's role and functionality.
+ *
+ * The description of the script, what it can do,
+ * and any further detail.
+ *
+ * @tutorial https://example.com/tutorial_1
+ * @tutorial(Tutorial 2) https://example.com/tutorial_2
+ * @experimental
+ */
+export default class DocumentationComments extends Node {
+
+    /**
+     * This is a multiline description of the variable v2.
+     * The type information below will be extracted for the documentation.
+     */
+    v2: number = 0;
+
+    /**
+     * As the following function is documented, even though its name starts with
+     * an underscore, it will appear in the help window.
+     */
+    _fn(p1: number, p2: string): number {
+        return 0;
+    }
+
+    /**
+     * This function is deprecated and should not appear in the help window.
+     * @deprecated Use [method _fn] instead
+     */
+    _deprecated() {}
+}
+````

internal/jsb_settings.cpp

@@ -12,6 +12,7 @@
 namespace jsb::internal
 {
 #ifdef TOOLS_ENABLED
+    static constexpr char kEdExperimentalJSDocDocumentationComments[] =     JSB_MODULE_NAME_STRING "/experimental/jsdoc_documentation_comments";
     static constexpr char kEdDebuggerPort[] =     JSB_MODULE_NAME_STRING "/debugger/editor_port";
     static constexpr char kEdIgnoredClasses[] =     JSB_MODULE_NAME_STRING "/codegen/ignored_classes";
     static constexpr char kEdAutogenPath[] =     JSB_MODULE_NAME_STRING "/codegen/autogen_path";
@@ -61,7 +62,8 @@ namespace jsb::internal
             if (EditorSettings::get_singleton())
             {
                 inited = true;
-                _EDITOR_DEF(kEdDebuggerPort, 9230, true);
+                _EDITOR_DEF(kEdExperimentalJSDocDocumentationComments, false, true);
+            	_EDITOR_DEF(kEdDebuggerPort, 9230, true);
                 _EDITOR_DEF(kEdIgnoredClasses, PackedStringArray(), false);
                 _EDITOR_DEF(kEdAutogenPath, "gen/godot", false);
                 _EDITOR_DEF(kEdGenSceneDTS, true, false);
@@ -174,6 +176,12 @@ namespace jsb::internal
         init_editor_settings();
         return EDITOR_GET(kEdCodegenUseProjectSettings);
     }
+
+	bool Settings::get_jsdoc_documentation_comments()
+    {
+    	init_editor_settings();
+    	return EDITOR_GET(kEdExperimentalJSDocDocumentationComments);
+    }
 #endif
 
     bool Settings::is_packaging_with_source_map()

internal/jsb_settings.h

@@ -57,6 +57,7 @@ namespace jsb::internal
         static bool get_autogen_resource_dts_on_save();
         static bool get_gen_resource_dts();
         static bool get_codegen_use_project_settings();
+        static bool get_jsdoc_documentation_comments();
 #endif
     };
 }

tests/project/gen/godot/tests/documentation-comments/DocumentationComments.nodes.gen.ts

@@ -0,0 +1,5 @@
+declare module "godot" {
+    interface SceneNodes {
+        "tests/documentation-comments/DocumentationComments.tscn": { Label: Label<{}>; };
+    }
+}

tests/project/gen/godot/tests/documentation-comments/DocumentationComments.tscn.gen.ts

@@ -0,0 +1,6 @@
+import DocumentationComments from "../../../../tests/documentation-comments/documentation-comments";
+declare module "godot" {
+    interface ResourceTypes {
+        "res://tests/documentation-comments/DocumentationComments.tscn": PackedScene<DocumentationComments>;
+    }
+}

tests/project/tests/documentation-comments/DocumentationComments.tscn

@@ -0,0 +1,11 @@
+[gd_scene load_steps=2 format=3 uid="uid://b33p5actrbp6s"]
+
+[ext_resource type="Script" uid="uid://b13817mvpqwo5" path="res://tests/documentation-comments/documentation-comments.ts" id="1_j3med"]
+
+[node name="DocumentationComments" type="Node2D"]
+script = ExtResource("1_j3med")
+
+[node name="Label" type="Label" parent="."]
+offset_right = 40.0
+offset_bottom = 23.0
+text = "DocumentationComments"

tests/project/tests/documentation-comments/documentation-comments.ts

@@ -0,0 +1,74 @@
+import { Node, Signal, Variant } from "godot";
+import { createClassBinder } from "godot.annotations";
+
+const bind = createClassBinder();
+
+/** This is a description of the below enum. */
+enum Direction {
+    /** Direction up. */
+    UP = 0,
+    /** Direction down. */
+    DOWN = 1,
+    /** Direction left. */
+    LEFT = 2,
+    /** Direction right. */
+    RIGHT = 3,
+}
+
+/**
+ * A brief description of the class's role and functionality.
+ *
+ * The description of the script, what it can do,
+ * and any further detail.
+ *
+ * @tutorial https://example.com/tutorial_1
+ * @tutorial(Tutorial 2) https://example.com/tutorial_2
+ * @experimental
+ */
+@bind()
+export default class DocumentationComments extends Node {
+    /** The description of a signal. */
+    @bind.signal()
+    accessor my_signal!: Signal<() => void>;
+
+    /** The description of a constant. */
+    static readonly GRAVITY = 9.8;
+
+    /** The description of the variable v1. */
+    v1: any;
+
+    /**
+     * This is a multiline description of the variable v2.
+     * The type information below will be extracted for the documentation.
+     */
+    v2: number = 0;
+
+    /**
+     * If the member has any annotation, the annotation should
+     * immediately precede it.
+     */
+    @bind.export(Variant.Type.TYPE_INT)
+    accessor v3: number = some_func();
+
+    /**
+     * As the following function is documented, even though its name starts with
+     * an underscore, it will appear in the help window.
+     */
+    _fn(p1: number, p2: string): number {
+        return 0;
+    }
+
+    // The below function isn't documented and its name starts with an underscore
+    // so it will treated as private and will not be shown in the help window.
+    _internal(): void {}
+
+    /**
+     * This function is deprecated and should not appear in the help window.
+     * @deprecated Use [method _fn] instead
+     */
+    _deprecated() {}
+}
+
+function some_func(): number {
+    return 0;
+}