Update info about BBCode in doc comments and Class Reference

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<class_@GDScript_annotation_@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<class_@GlobalScope_constant_KEY_ESCAPE>`. |
-+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
-| [enum Class.name]       | Link to enum ``name`` in class ``Class``        | See [enum Mesh.ArrayType].              | See :ref:`ArrayType<enum_Mesh_ArrayType>`.                                  |
-+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
-| [method Class.name]     | Link to method ``name`` in class ``Class``      | Call [method Node3D.hide].              | Call :ref:`hide<class_Node3D_method_hide>`.                                 |
-+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
-| [member Class.name]     | Link to member ``name`` in class ``Class``      | Get [member Node2D.scale].              | Get :ref:`scale<class_Node2D_property_scale>`.                              |
-+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
-| [signal Class.name]     | Link to signal ``name`` in class ``Class``      | Emit [signal Node.renamed].             | Emit :ref:`renamed<class_Node_signal_renamed>`.                             |
-+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
-| [theme_item Class.name] | Link to theme item ``name`` in class ``Class``  | See [theme_item GraphNode.position].    | See :ref:`position<class_GraphNode_theme_style_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 <class_@GDScript_annotation_@export>`.   |
+| | Link to annotation          |                                         |                                                                      |
++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[constant Class.name]``   | ``See [constant @GlobalScope.KEY_F1].`` | See :ref:`@GlobalScope.KEY_F1 <class_@GlobalScope_constant_KEY_F1>`. |
+| | Link to constant            |                                         |                                                                      |
++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[enum Class.name]``       | ``See [enum Mesh.ArrayType].``          | See :ref:`Mesh.ArrayType <enum_Mesh_ArrayType>`.                     |
+| | Link to enum                |                                         |                                                                      |
++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[method Class.name]``     | ``Call [method Node3D.hide].``          | Call :ref:`Node3D.hide() <class_Node3D_method_hide>`.                |
+| | Link to method              |                                         |                                                                      |
++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[member Class.name]``     | ``Get [member Node2D.scale].``          | Get :ref:`Node2D.scale <class_Node2D_property_scale>`.               |
+| | Link to member              |                                         |                                                                      |
++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[signal Class.name]``     | ``Emit [signal Node.renamed].``         | Emit :ref:`Node.renamed <class_Node_signal_renamed>`.                |
+| | Link to signal              |                                         |                                                                      |
++-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[theme_item Class.name]`` | ``See [theme_item Label.font].``        | See :ref:`Label.font <class_Label_theme_font_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.*                                                      |
-+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
-
-Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``,
-always use **four spaces** for indentation. The parser will delete tabs. For
-example:
++----------------------------------------+---------------------------------------+--------------------------+
+| 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       |                                       |                          |
++----------------------------------------+---------------------------------------+--------------------------+
+
+.. 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
 

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::
+
+    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::
 
-.. 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.
+    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 <doc_bbcode_in_
 
 Godot's class reference supports BBCode-like tags. They add nice formatting to the text which could also
 be used in the documentation. See also :ref:`class reference bbcode <doc_class_reference_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<class_@GDScript_annotation_@export>`.           |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-| [annotation Class.name]   | Link to another class's        | See                                 | See                                                                     |
-|                           | annotation, many default       | [annotation @GDScript.@export].     | :ref:`@GDScript.@export<class_@GDScript_annotation_@export>`.           |
-|                           | annotations are in             |                                     |                                                                         |
-|                           | ``@GDScript``                  |                                     |                                                                         |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-| [constant name]           | Link to a constant in this     | See                                 | See                                                                     |
-|                           | class                          | [constant KEY_ESCAPE].              | :ref:`@GlobalScope.KEY_ESCAPE<class_@GlobalScope_constant_KEY_ESCAPE>`. |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-| [constant Class.name]     | Link to another class's        | See                                 | See                                                                     |
-|                           | constant                       | [constant @GlobalScope.KEY_ESCAPE]. | :ref:`@GlobalScope.KEY_ESCAPE<class_@GlobalScope_constant_KEY_ESCAPE>`. |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-| [enum enumname]           | Link to an enum in this class  | See [enum ArrayType].               | See :ref:`ArrayType <enum_Mesh_ArrayType>`.                             |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-| [enum Class.enumname]     | Link to another class's enum   | See [enum Mesh.ArrayType].          | See :ref:`ArrayType <enum_Mesh_ArrayType>`.                             |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-| [method methodname]       | Link to a method in this class | Call [method hide].                 | Call :ref:`hide <class_Node3D_method_hide>`.                            |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-| [method Class.methodname] | Link to another class's method | Call [method Node3D.hide].          | Call :ref:`hide <class_Node3D_method_hide>`.                            |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-| [member membername]       | Link to a member in this class | Get [member scale].                 | Get :ref:`scale <class_Node2D_property_scale>`.                         |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-| [member Class.membername] | Link to another class's member | Get [member Node2D.scale].          | Get :ref:`scale <class_Node2D_property_scale>`.                         |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-| [signal signalname]       | Link to a signal in this class | Emit [signal renamed].              | Emit :ref:`renamed <class_node_signal_renamed>`.                        |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed].         | Emit :ref:`renamed <class_node_signal_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.*                                                            |
-+---------------------------+--------------------------------+-------------------------------------+-------------------------------------------------------------------------+
-
-.. warning:: Use ``[codeblock]`` for pre-formatted code blocks. Inside
-             ``[codeblock]``, always use **four spaces** for indentation
-             (the parser will delete tabs).
++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| 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 <class_@GDScript_annotation_@export>`.   |
+| | Link to annotation                 |                                         |                                                                      |
++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[constant Class.name]``          | ``See [constant @GlobalScope.KEY_F1].`` | See :ref:`@GlobalScope.KEY_F1 <class_@GlobalScope_constant_KEY_F1>`. |
+| | Link to constant                   |                                         |                                                                      |
++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[enum Class.name]``              | ``See [enum Mesh.ArrayType].``          | See :ref:`Mesh.ArrayType <enum_Mesh_ArrayType>`.                     |
+| | Link to enum                       |                                         |                                                                      |
++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[method Class.name]``            | ``Call [method Node3D.hide].``          | Call :ref:`Node3D.hide() <class_Node3D_method_hide>`.                |
+| | Link to method                     |                                         |                                                                      |
++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[member Class.name]``            | ``Get [member Node2D.scale].``          | Get :ref:`Node2D.scale <class_Node2D_property_scale>`.               |
+| | Link to member                     |                                         |                                                                      |
++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[signal Class.name]``            | ``Emit [signal Node.renamed].``         | Emit :ref:`Node.renamed <class_Node_signal_renamed>`.                |
+| | Link to signal                     |                                         |                                                                      |
++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+| | ``[theme_item Class.name]``        | ``See [theme_item Label.font].``        | See :ref:`Label.font <class_Label_theme_font_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       |                                         |                                                                      |
++--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
+
+.. 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

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 <doc_gdscript_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 ``<variable>: <type>``:
 
 ::
 
-   var health: int = 0
+    var health: int = 0
 
 To declare the return type of a function, use ``-> <type>``:
 
 ::
 
-   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<doc_gdscript_static_typing_safe_lines>` than the first.
 
@@ -952,6 +960,6 @@ This option is also considered more :ref:`type-safe<doc_gdscript_static_typing_s
 
 ::
 
-   # The compiler can't infer the exact type and will use Node
-   # instead of ProgressBar.
-   @onready var health_bar := get_node("UI/LifeBar")
+    # The compiler can't infer the exact type and will use Node
+    # instead of ProgressBar.
+    @onready var health_bar := get_node("UI/LifeBar")