diff --git a/tutorials/scripting/c_sharp/diagnostics/GD0108.rst b/tutorials/scripting/c_sharp/diagnostics/GD0108.rst new file mode 100644 index 00000000000..d3254f85bf9 --- /dev/null +++ b/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. diff --git a/tutorials/scripting/c_sharp/diagnostics/GD0109.rst b/tutorials/scripting/c_sharp/diagnostics/GD0109.rst new file mode 100644 index 00000000000..1039205cf46 --- /dev/null +++ b/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. diff --git a/tutorials/scripting/c_sharp/diagnostics/GD0110.rst b/tutorials/scripting/c_sharp/diagnostics/GD0110.rst new file mode 100644 index 00000000000..dc020e847d8 --- /dev/null +++ b/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. diff --git a/tutorials/scripting/c_sharp/diagnostics/GD0111.rst b/tutorials/scripting/c_sharp/diagnostics/GD0111.rst new file mode 100644 index 00000000000..7445eab0d8b --- /dev/null +++ b/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 diff --git a/tutorials/scripting/c_sharp/diagnostics/index.rst b/tutorials/scripting/c_sharp/diagnostics/index.rst index 9a45f873190..0b5cd1c55f1 100644 --- a/tutorials/scripting/c_sharp/diagnostics/index.rst +++ b/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