Merge pull request #10711 from raulsntos/dotnet/export-tool-diagnostics

C#: Document `[ExportToolButton]` diagnostics

Author: tetrapod00

tutorials/scripting/c_sharp/diagnostics/GD0108.rst

@@ -0,0 +1,51 @@
+GD0108: The exported tool button is not in a tool class
+=======================================================
+
+====================================  ======================================
+                                      Value
+====================================  ======================================
+**Rule ID**                           GD0108
+**Category**                          Usage
+**Fix is breaking or non-breaking**   Non-breaking
+**Enabled by default**                Yes
+====================================  ======================================
+
+Cause
+-----
+
+A property is annotated with the ``[ExportToolButton]`` attribute in a class that
+is **not** annotated with the ``[Tool]`` attribute.
+
+Rule description
+----------------
+
+The ``[ExportToolButton]`` is used to create clickable buttons in the inspector so,
+like every other script that runs in the editor, it needs to be annotated with the
+``[Tool]`` attribute.
+
+.. code-block:: csharp
+    :emphasize-lines: 1
+
+    [Tool]
+    public partial class MyNode : Node
+    {
+        [ExportToolButton("Click me!")]
+        public Callable ClickMeButton => Callable.From(ClickMe);
+
+        private static void ClickMe()
+        {
+            GD.Print("Hello world!");
+        }
+    }
+
+How to fix violations
+---------------------
+
+To fix a violation of this rule, add the ``[Tool]`` attribute to the class that
+contains the member annotated with the ``[ExportToolButton]`` attribute.
+
+When to suppress warnings
+-------------------------
+
+Do not suppress a warning from this rule. The clickable buttons in the inspector
+won't be functional if their script is not annotated with the ``[Tool]`` attribute.

tutorials/scripting/c_sharp/diagnostics/GD0109.rst

@@ -0,0 +1,34 @@
+GD0109: The '[ExportToolButton]' attribute cannot be used with another '[Export]' attribute
+===========================================================================================
+
+====================================  ======================================
+                                      Value
+====================================  ======================================
+**Rule ID**                           GD0109
+**Category**                          Usage
+**Fix is breaking or non-breaking**   Non-breaking
+**Enabled by default**                Yes
+====================================  ======================================
+
+Cause
+-----
+
+A property is annotated with both the ``[ExportToolButton]`` and the ``[Export]``
+attributes.
+
+Rule description
+----------------
+
+The ``[ExportToolButton]`` attribute already implies exporting the member, so
+the ``[Export]`` is unnecessary.
+
+How to fix violations
+---------------------
+
+To fix a violation of this rule, remove the ``[Export]`` attribute.
+
+When to suppress warnings
+-------------------------
+
+Do not suppress a warning from this rule. Multiple export attributes may lead
+to duplicated members, resulting in unexpected runtime errors.

tutorials/scripting/c_sharp/diagnostics/GD0110.rst

@@ -0,0 +1,38 @@
+GD0110: The exported tool button is not a Callable
+==================================================
+
+====================================  ======================================
+                                      Value
+====================================  ======================================
+**Rule ID**                           GD0110
+**Category**                          Usage
+**Fix is breaking or non-breaking**   Breaking - If the property's type is changed to ``Callable``
+
+                                      Non-breaking - If the ``[ExportToolButton]`` is replaced with ``[Export]``
+**Enabled by default**                Yes
+====================================  ======================================
+
+Cause
+-----
+
+A property of a type different from ``Callable`` is annotated with the
+``[ExportToolButton]`` attribute.
+
+Rule description
+----------------
+
+The ``[ExportToolButton]`` attribute is used to create clickable buttons in the inspector so,
+the property must be a ``Callable`` that will be executed when clicking the button.
+
+How to fix violations
+---------------------
+
+To fix a violation of this rule, change the type of the property to ``Callable``.
+Alternatively, if you intended to export a normal property, replace the
+``[ExportToolButton]`` attribute with ``[Export]``.
+
+When to suppress warnings
+-------------------------
+
+Do not suppress a warning from this rule. The exported property must be a ``Callable``
+so it can executed in the editor when clicking the button in the inspector.

tutorials/scripting/c_sharp/diagnostics/GD0111.rst

@@ -0,0 +1,51 @@
+GD0111: The exported tool button must be an expression-bodied property
+======================================================================
+
+====================================  ======================================
+                                      Value
+====================================  ======================================
+**Rule ID**                           GD0111
+**Category**                          Usage
+**Fix is breaking or non-breaking**   Non-breaking
+**Enabled by default**                Yes
+====================================  ======================================
+
+Cause
+-----
+
+A property is annotated with the ``[ExportToolButton]`` attribute but it's not
+an `expression-bodied property`_.
+
+Rule description
+----------------
+
+When reloading the .NET assembly, Godot will attempt to serialize exported
+members to preserve their values. A field or a property with a backing field
+that stores a ``Callable`` may prevent the unloading of the assembly.
+
+An expression-bodied property doesn't have a backing field and won't store
+the ``Callable``, so Godot won't attempt to serialize it, which should result
+in the successful reloading of the .NET assembly.
+
+.. code-block:: csharp
+
+    [ExportToolButton("Click me!")]
+    public Callable ValidClickMeButton => Callable.From(ClickMe);
+
+    // Invalid because the Callable will be stored in the property's backing field.
+    [ExportToolButton("Click me!")]
+    public Callable InvalidClickMeButton { get; } = Callable.From(ClickMe);
+
+How to fix violations
+---------------------
+
+To fix a violation of this rule, replace the property implementation with an
+`expression-bodied property`_.
+
+When to suppress warnings
+-------------------------
+
+Do not suppress a warning from this rule. ``Callable`` instances may prevent
+the .NET assembly from unloading.
+
+.. _expression-bodied property: https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/statements-expressions-operators/expression-bodied-members#properties

tutorials/scripting/c_sharp/diagnostics/index.rst

@@ -25,6 +25,10 @@ or unsupported code and let you know that something is wrong during build time.
    GD0105
    GD0106
    GD0107
+   GD0108
+   GD0109
+   GD0110
+   GD0111
    GD0201
    GD0202
    GD0203