diff --git a/contributing/documentation/class_reference_primer.rst b/contributing/documentation/class_reference_primer.rst index 29f789479..c73744c31 100644 --- a/contributing/documentation/class_reference_primer.rst +++ b/contributing/documentation/class_reference_primer.rst @@ -134,62 +134,93 @@ Linking Whenever you link to a member of another class, you need to specify the class name. For links to the same class, the class name is optional and can be omitted. -+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+ -| Tag | Effect | Usage | Result | -+=========================+=================================================+=========================================+=============================================================================+ -| [Class] | Link to class ``Class`` | Move the [Sprite2D]. | Move the :ref:`class_Sprite2D`. | -+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+ -| [annotation Class.name] | Link to annotation ``name`` in class ``Class``, | See [annotation @GDScript.@export]. | See :ref:`@GDScript.@export`. | -| | many default annotations are in ``@GDScript`` | | | -+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+ -| [constant Class.name] | Link to constant ``name`` in class ``Class`` | See [constant @GlobalScope.KEY_ESCAPE]. | See :ref:`@GlobalScope.KEY_ESCAPE`. | -+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+ -| [enum Class.name] | Link to enum ``name`` in class ``Class`` | See [enum Mesh.ArrayType]. | See :ref:`ArrayType`. | -+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+ -| [method Class.name] | Link to method ``name`` in class ``Class`` | Call [method Node3D.hide]. | Call :ref:`hide`. | -+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+ -| [member Class.name] | Link to member ``name`` in class ``Class`` | Get [member Node2D.scale]. | Get :ref:`scale`. | -+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+ -| [signal Class.name] | Link to signal ``name`` in class ``Class`` | Emit [signal Node.renamed]. | Emit :ref:`renamed`. | -+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+ -| [theme_item Class.name] | Link to theme item ``name`` in class ``Class`` | See [theme_item GraphNode.position]. | See :ref:`position`. | -+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+ ++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| Tag and Description | Example | Result | ++===============================+=========================================+======================================================================+ +| | ``[Class]`` | ``Move the [Sprite2D].`` | Move the :ref:`class_Sprite2D`. | +| | Link to class | | | ++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[annotation Class.name]`` | ``See [annotation @GDScript.@export].`` | See :ref:`@GDScript.@export `. | +| | Link to annotation | | | ++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[constant Class.name]`` | ``See [constant @GlobalScope.KEY_F1].`` | See :ref:`@GlobalScope.KEY_F1 `. | +| | Link to constant | | | ++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[enum Class.name]`` | ``See [enum Mesh.ArrayType].`` | See :ref:`Mesh.ArrayType `. | +| | Link to enum | | | ++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[method Class.name]`` | ``Call [method Node3D.hide].`` | Call :ref:`Node3D.hide() `. | +| | Link to method | | | ++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[member Class.name]`` | ``Get [member Node2D.scale].`` | Get :ref:`Node2D.scale `. | +| | Link to member | | | ++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[signal Class.name]`` | ``Emit [signal Node.renamed].`` | Emit :ref:`Node.renamed `. | +| | Link to signal | | | ++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[theme_item Class.name]`` | ``See [theme_item Label.font].`` | See :ref:`Label.font `. | +| | Link to theme item | | | ++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+ + +.. note:: + + Currently only :ref:`class_@GDScript` has annotations. Formatting text """"""""""""""" -+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+ -| Tag | Effect | Usage | Result | -+============================+=====================================================+=====================================+===================================================================+ -| [param name] | Formats a parameter name (as code) | Takes [param size] for the size. | Takes ``size`` for the size. | -+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+ -| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. | -+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+ -| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. | -+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+ -| [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. | -+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+ ++--------------------------------------+--------------------------------------+------------------------------+ +| Tag and Description | Example | Result | ++======================================+======================================+==============================+ +| | ``[param name]`` | ``Takes [param size] for the size.`` | Takes ``size`` for the size. | +| | Formats a parameter name (as code) | | | ++--------------------------------------+--------------------------------------+------------------------------+ +| | ``[br]`` | | ``Line 1.[br]`` | | Line 1. | +| | Line break | | ``Line 2.`` | | Line 2. | ++--------------------------------------+--------------------------------------+------------------------------+ +| | ``[b]`` ``[/b]`` | ``Some [b]bold[/b] text.`` | Some **bold** text. | +| | Bold | | | ++--------------------------------------+--------------------------------------+------------------------------+ +| | ``[i]`` ``[/i]`` | ``Some [i]italic[/i] text.`` | Some *italic* text. | +| | Italic | | | ++--------------------------------------+--------------------------------------+------------------------------+ +| | ``[kbd]`` ``[/kbd]`` | ``Some [kbd]Ctrl + C[/kbd] key.`` | Some :kbd:`Ctrl + C` key. | +| | Keyboard/mouse shortcut | | | ++--------------------------------------+--------------------------------------+------------------------------+ Formatting code """"""""""""""" -+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+ -| Tag | Effect | Usage | Result | -+============================+=====================================================+=====================================+===================================================================+ -| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. | -+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+ -| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* | -+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+ -| [codeblocks] [/codeblocks] | [codeblock] for multiple languages | *See below.* | *See below.* | -+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+ -| [gdscript] [/gdscript] | GDScript codeblock tab in codeblocks | *See below.* | *See below.* | -+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+ -| [csharp] [/csharp] | C# codeblock tab in codeblocks | *See below.* | *See below.* | -+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+ ++----------------------------------------+---------------------------------------+--------------------------+ +| Tag and Description | Example | Result | ++========================================+=======================================+==========================+ +| | ``[code]`` ``[/code]`` | ``Some [code]monospace[/code] text.`` | Some ``monospace`` text. | +| | Monospace | | | ++----------------------------------------+---------------------------------------+--------------------------+ +| | ``[codeblock]`` ``[/codeblock]`` | *See below.* | *See below.* | +| | Multiline preformatted block | | | ++----------------------------------------+---------------------------------------+--------------------------+ +| | ``[codeblocks]`` ``[/codeblocks]`` | *See below.* | *See below.* | +| | Codeblock for multiple languages | | | ++----------------------------------------+---------------------------------------+--------------------------+ +| | ``[gdscript]`` ``[/gdscript]`` | *See below.* | *See below.* | +| | GDScript codeblock tab in codeblocks | | | ++----------------------------------------+---------------------------------------+--------------------------+ +| | ``[csharp]`` ``[/csharp]`` | *See below.* | *See below.* | +| | C# codeblock tab in codeblocks | | | ++----------------------------------------+---------------------------------------+--------------------------+ -Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``, -always use **four spaces** for indentation. The parser will delete tabs. For -example: +.. note:: + + 1. ``[code]`` disables BBCode until the parser encounters ``[/code]``. + 2. ``[codeblock]`` disables BBCode until the parser encounters ``[/codeblock]``. + +.. warning:: + + Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``, + always use **four spaces** for indentation. The parser will delete tabs. + +For example: .. code-block:: none diff --git a/tutorials/scripting/gdscript/gdscript_documentation_comments.rst b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst index 522905531..86492b1e6 100644 --- a/tutorials/scripting/gdscript/gdscript_documentation_comments.rst +++ b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst @@ -35,29 +35,33 @@ Tags | Description | Use one blank line to separate the description from | | | the brief. | +-------------------+--------------------------------------------------------+ -| Tutorial | ``@tutorial[( The Title Here )]:`` | -| | | +| Tutorial | | ``@tutorial:`` | +| | | ``@tutorial(The Title Here):`` | +-------------------+--------------------------------------------------------+ -**Example:** +For example: :: extends Node2D - - ## A brief description of your script. + ## A brief description of the class's role and functionality. ## - ## A more detailed description of the script. + ## The description of the script, what it can do, + ## and any further detail. ## ## @tutorial: https://the/tutorial1/url.com ## @tutorial(Tutorial2): https://the/tutorial2/url.com -.. warning:: If there is any space in between the tag name and colon, for example - ``@tutorial :``, it won't be treated as a valid tag and will be ignored. +.. warning:: -.. note:: When the description spans multiple lines, the preceding and trailing white - spaces will be stripped and joined with a single space. To preserve the line - break use ``[br]``. See also `BBCode and class reference`_ below. + If there is any space in between the tag name and colon, for example + ``@tutorial :``, it won't be treated as a valid tag and will be ignored. + +.. note:: + + When the description spans multiple lines, the preceding and trailing white + spaces will be stripped and joined with a single space. To preserve the line + break use ``[br]``. See also `BBCode and class reference`_ below. Documenting script members -------------------------- @@ -82,14 +86,13 @@ Members that are applicable for documentation: - Enum - Enum value -Examples --------- +Example +------- :: extends Node2D - - ## A brief description of your script. + ## A brief description of the class's role and functionality. ## ## The description of the script, what it can do, ## and any further detail. @@ -97,18 +100,6 @@ Examples ## @tutorial: https://the/tutorial1/url.com ## @tutorial(Tutorial2): https://the/tutorial2/url.com - ## The description of the variable v1. - var v1 - - ## This is a multi line description of the variable v2. The type - ## information below will be extracted for the documentation. - var v2: int - - ## If the member has any annotation, the annotation should - ## immediately precede it. - @onready - var v3 := some_func() - ## The description of a constant. const GRAVITY = 9.8 @@ -124,16 +115,34 @@ Examples RIGHT = 3, ## Direction right. } + ## The description of a constant. + const GRAVITY = 9.8 + + ## The description of the variable v1. + var v1 + + ## This is a multiline description of the variable v2.[br] + ## The type information below will be extracted for the documentation. + var v2: int + + ## If the member has any annotation, the annotation should + ## immediately precede it. + @export + var v3 := some_func() + + ## As the following function is documented, even though its name starts with ## an underscore, it will appear in the help window. func _fn(p1: int, p2: String) -> int: 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. func _internal() -> void: pass + ## Documenting an inner class. ## ## The same rules apply here. The documentation must @@ -145,6 +154,7 @@ Examples ## Inner class variable v4. var v4 + ## Inner class function fn. func fn(): pass @@ -158,73 +168,83 @@ URLs, animation effects, etc. can be added with the :ref:`bbcode `. + +Whenever you link to a member of another class, you need to specify the class name. +For links to the same class, the class name is optional and can be omitted. + Here's the list of available tags: -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| Tag | Effect | Usage | Result | -+===========================+================================+=====================================+=========================================================================+ -| [Class] | Link a class | Move the [Sprite2D]. | Move the :ref:`class_Sprite2D`. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [annotation name] | Link to an annotation in this | See | See | -| | class | [annotation @export]. | :ref:`@GDScript.@export`. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [annotation Class.name] | Link to another class's | See | See | -| | annotation, many default | [annotation @GDScript.@export]. | :ref:`@GDScript.@export`. | -| | annotations are in | | | -| | ``@GDScript`` | | | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [constant name] | Link to a constant in this | See | See | -| | class | [constant KEY_ESCAPE]. | :ref:`@GlobalScope.KEY_ESCAPE`. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [constant Class.name] | Link to another class's | See | See | -| | constant | [constant @GlobalScope.KEY_ESCAPE]. | :ref:`@GlobalScope.KEY_ESCAPE`. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [enum enumname] | Link to an enum in this class | See [enum ArrayType]. | See :ref:`ArrayType `. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [enum Class.enumname] | Link to another class's enum | See [enum Mesh.ArrayType]. | See :ref:`ArrayType `. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [method methodname] | Link to a method in this class | Call [method hide]. | Call :ref:`hide `. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [method Class.methodname] | Link to another class's method | Call [method Node3D.hide]. | Call :ref:`hide `. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [member membername] | Link to a member in this class | Get [member scale]. | Get :ref:`scale `. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get :ref:`scale `. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit :ref:`renamed `. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit :ref:`renamed `. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [br] | Line break | | Line 1.[br] | | Line 1. | -| | | | Line 2. | | Line 2. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ -| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* | -+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+ ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| Tag and Description | Example | Result | ++======================================+=========================================+======================================================================+ +| | ``[Class]`` | ``Move the [Sprite2D].`` | Move the :ref:`class_Sprite2D`. | +| | Link to class | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[annotation Class.name]`` | ``See [annotation @GDScript.@export].`` | See :ref:`@GDScript.@export `. | +| | Link to annotation | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[constant Class.name]`` | ``See [constant @GlobalScope.KEY_F1].`` | See :ref:`@GlobalScope.KEY_F1 `. | +| | Link to constant | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[enum Class.name]`` | ``See [enum Mesh.ArrayType].`` | See :ref:`Mesh.ArrayType `. | +| | Link to enum | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[method Class.name]`` | ``Call [method Node3D.hide].`` | Call :ref:`Node3D.hide() `. | +| | Link to method | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[member Class.name]`` | ``Get [member Node2D.scale].`` | Get :ref:`Node2D.scale `. | +| | Link to member | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[signal Class.name]`` | ``Emit [signal Node.renamed].`` | Emit :ref:`Node.renamed `. | +| | Link to signal | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[theme_item Class.name]`` | ``See [theme_item Label.font].`` | See :ref:`Label.font `. | +| | Link to theme item | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[param name]`` | ``Takes [param size] for the size.`` | Takes ``size`` for the size. | +| | Formats a parameter name (as code) | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[br]`` | | ``Line 1.[br]`` | | Line 1. | +| | Line break | | ``Line 2.`` | | Line 2. | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[b]`` ``[/b]`` | ``Some [b]bold[/b] text.`` | Some **bold** text. | +| | Bold | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[i]`` ``[/i]`` | ``Some [i]italic[/i] text.`` | Some *italic* text. | +| | Italic | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[kbd]`` ``[/kbd]`` | ``Some [kbd]Ctrl + C[/kbd] key.`` | Some :kbd:`Ctrl + C` key. | +| | Keyboard/mouse shortcut | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[code]`` ``[/code]`` | ``Some [code]monospace[/code] text.`` | Some ``monospace`` text. | +| | Monospace | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ +| | ``[codeblock]`` ``[/codeblock]`` | *See below.* | *See below.* | +| | Multiline preformatted block | | | ++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+ -.. warning:: Use ``[codeblock]`` for pre-formatted code blocks. Inside - ``[codeblock]``, always use **four spaces** for indentation - (the parser will delete tabs). +.. note:: + + 1. Currently only :ref:`class_@GDScript` has annotations. + 2. ``[code]`` disables BBCode until the parser encounters ``[/code]``. + 3. ``[codeblock]`` disables BBCode until the parser encounters ``[/codeblock]``. + +.. warning:: + + Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``, + always use **four spaces** for indentation (the parser will delete tabs). :: - ## The do_something method for this plugin. before using the - ## method you first have to initialize [MyPlugin]. - ## see : [method initialize] - ## [color=yellow]Warning:[/color] always [method clean] after use. + ## Do something for this plugin. Before using the method + ## you first have to [method initialize] [MyPlugin].[br] + ## [color=yellow]Warning:[/color] Always [method clean] after use.[br] ## Usage: - ## [codeblock] - ## func _ready(): - ## the_plugin.initialize() - ## the_plugin.do_something() - ## the_plugin.clean() - ## [/codeblock] + ## [codeblock] + ## func _ready(): + ## the_plugin.initialize() + ## the_plugin.do_something() + ## the_plugin.clean() + ## [/codeblock] func do_something(): pass diff --git a/tutorials/scripting/gdscript/gdscript_styleguide.rst b/tutorials/scripting/gdscript/gdscript_styleguide.rst index ac4322b8e..ef314e186 100644 --- a/tutorials/scripting/gdscript/gdscript_styleguide.rst +++ b/tutorials/scripting/gdscript/gdscript_styleguide.rst @@ -19,8 +19,10 @@ and ask fellow developers for insights. In general, keeping your code consistent in your projects and within your team is more important than following this guide to a tee. -.. note:: Godot's built-in script editor uses a lot of these conventions - by default. Let it help you. +.. note:: + + Godot's built-in script editor uses a lot of these conventions + by default. Let it help you. Here is a complete class example based on these guidelines: @@ -28,9 +30,10 @@ Here is a complete class example based on these guidelines: class_name StateMachine extends Node - # Hierarchical State machine for the player. - # Initializes states and delegates engine callbacks - # (_physics_process, _unhandled_input) to the state. + ## Hierarchical State machine for the player. + ## + ## Initializes states and delegates engine callbacks ([method Node._physics_process], + ## [method Node._unhandled_input]) to the state. signal state_changed(previous, new) @@ -46,11 +49,11 @@ Here is a complete class example based on these guidelines: func _init(): add_to_group("state_machine") - - + + func _enter_tree(): print("this happens before the ready method!") - + func _ready(): state_changed.connect(_on_state_changed) @@ -287,8 +290,10 @@ Surround functions and class definitions with two blank lines: Use one blank line inside functions to separate logical sections. -.. note:: We use a single line between classes and function definitions in the class reference and - in short code snippets in this documentation. +.. note:: + + We use a single line between classes and function definitions in the class reference and + in short code snippets in this documentation. Line length ~~~~~~~~~~~ @@ -331,7 +336,7 @@ The only exception to that rule is the ternary operator: :: - next_state = "idle" if is_on_floor() else "fall" + next_state = "idle" if is_on_floor() else "fall" Format multiline statements for readability ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -467,9 +472,9 @@ This helps differentiate text comments from disabled code. .. note:: - In the script editor, to toggle the selected code commented, press - :kbd:`Ctrl + K`. This feature adds a single # sign at the start - of the selected lines. + In the script editor, to toggle the selected code commented, press + :kbd:`Ctrl + K`. This feature adds a single # sign at the start + of the selected lines. Whitespace ~~~~~~~~~~ @@ -636,7 +641,7 @@ Use PascalCase for class and node names: :: - extends CharacterBody3D + extends CharacterBody3D Also use PascalCase when loading a class into a constant or a variable: @@ -651,16 +656,16 @@ Use snake\_case to name functions and variables: :: - var particle_effect - func load_level(): + var particle_effect + func load_level(): Prepend a single underscore (\_) to virtual methods functions the user must override, private functions, and private variables: :: - var _counter = 0 - func _recalculate_path(): + var _counter = 0 + func _recalculate_path(): Signals ~~~~~~~ @@ -745,22 +750,25 @@ Class declaration If the code is meant to run in the editor, place the ``@tool`` annotation on the first line of the script. -Follow with the `class_name` if necessary. You can turn a GDScript file into a +Follow with the ``class_name`` if necessary. You can turn a GDScript file into a global type in your project using this feature. For more information, see :ref:`doc_gdscript`. -Then, add the `extends` keyword if the class extends a built-in type. +Then, add the ``extends`` keyword if the class extends a built-in type. -Following that, you should have the class's optional docstring as comments. You -can use that to explain the role of your class to your teammates, how it works, +Following that, you should have the class's optional +:ref:`documentation comments `. +You can use that to explain the role of your class to your teammates, how it works, and how other developers should use it, for example. :: - class_name MyNode - extends Node - # A brief description of the class's role and functionality. - # Longer description. + class_name MyNode + extends Node + ## A brief description of the class's role and functionality. + ## + ## The description of the script, what it can do, + ## and any further detail. Signals and properties ~~~~~~~~~~~~~~~~~~~~~~ @@ -776,32 +784,32 @@ variables, in that order. :: - signal spawn_player(position) + signal spawn_player(position) - enum Jobs {KNIGHT, WIZARD, ROGUE, HEALER, SHAMAN} + enum Jobs {KNIGHT, WIZARD, ROGUE, HEALER, SHAMAN} - const MAX_LIVES = 3 + const MAX_LIVES = 3 - @export var job: Jobs = Jobs.KNIGHT - @export var max_health = 50 - @export var attack = 5 + @export var job: Jobs = Jobs.KNIGHT + @export var max_health = 50 + @export var attack = 5 - var health = max_health: - set(new_health): - health = new_health + var health = max_health: + set(new_health): + health = new_health - var _speed = 300.0 + var _speed = 300.0 - @onready var sword = get_node("Sword") - @onready var gun = get_node("Gun") + @onready var sword = get_node("Sword") + @onready var gun = get_node("Gun") .. note:: - The GDScript compiler evaluates onready variables right before the ``_ready`` - callback. You can use that to cache node dependencies, that is to say, to get - child nodes in the scene that your class relies on. This is what the example - above shows. + The GDScript compiler evaluates onready variables right before the ``_ready`` + callback. You can use that to cache node dependencies, that is to say, to get + child nodes in the scene that your class relies on. This is what the example + above shows. Member variables ~~~~~~~~~~~~~~~~ @@ -881,13 +889,13 @@ To declare a variable's type, use ``: ``: :: - var health: int = 0 + var health: int = 0 To declare the return type of a function, use ``-> ``: :: - func heal(amount: int) -> void: + func heal(amount: int) -> void: Inferred types ~~~~~~~~~~~~~~ @@ -902,8 +910,8 @@ otherwise prefer writing the type explicitly. :: - var health: int = 0 # The type can be int or float, and thus should be stated explicitly. - var direction := Vector3(1, 2, 3) # The type is clearly inferred as Vector3. + var health: int = 0 # The type can be int or float, and thus should be stated explicitly. + var direction := Vector3(1, 2, 3) # The type is clearly inferred as Vector3. Include the type hint when the type is ambiguous, and omit the type hint when it's redundant. @@ -914,11 +922,11 @@ omit the type hint when it's redundant. :: - var health := 0 # Typed as int, but it could be that float was intended. - var direction: Vector3 = Vector3(1, 2, 3) # The type hint has redundant information. + var health := 0 # Typed as int, but it could be that float was intended. + var direction: Vector3 = Vector3(1, 2, 3) # The type hint has redundant information. - # What type is this? It's not immediately clear to the reader, so it's bad. - var value := complex_function() + # What type is this? It's not immediately clear to the reader, so it's bad. + var value := complex_function() In some cases, the type must be stated explicitly, otherwise the behavior will not be as expected because the compiler will only be able to use @@ -932,7 +940,7 @@ should set the type explicitly. :: - @onready var health_bar: ProgressBar = get_node("UI/LifeBar") + @onready var health_bar: ProgressBar = get_node("UI/LifeBar") Alternatively, you can use the ``as`` keyword to cast the return type, and that type will be used to infer the type of the var. @@ -941,8 +949,8 @@ that type will be used to infer the type of the var. :: - @onready var health_bar := get_node("UI/LifeBar") as ProgressBar - # health_bar will be typed as ProgressBar + @onready var health_bar := get_node("UI/LifeBar") as ProgressBar + # health_bar will be typed as ProgressBar This option is also considered more :ref:`type-safe` than the first. @@ -952,6 +960,6 @@ This option is also considered more :ref:`type-safe