Merge pull request #9313 from dalexeev/update-doc-markup-docs

Update class reference and doc comment markup documentation

contributing/documentation/class_reference_primer.rst

@@ -134,33 +134,42 @@ 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 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          |                                         |                                                                      |
-+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
++--------------------------------+-----------------------------------------+--------------------------------------------------------------+
+| Tag and Description            | Example                                 | Result                                                       |
++================================+=========================================+==============================================================+
+| | ``[Class]``                  | ``Move the [Sprite2D].``                | Move the :ref:`class_Sprite2D`.                              |
+| | Link to class                |                                         |                                                              |
++--------------------------------+-----------------------------------------+--------------------------------------------------------------+
+| | ``[annotation Class.name]``  | ``See [annotation @GDScript.@rpc].``    | See :ref:`@GDScript.@rpc <class_@GDScript_annotation_@rpc>`. |
+| | Link to annotation           |                                         |                                                              |
++--------------------------------+-----------------------------------------+--------------------------------------------------------------+
+| | ``[constant Class.name]``    | ``See [constant Color.RED].``           | See :ref:`Color.RED <class_Color_constant_RED>`.             |
+| | Link to constant             |                                         |                                                              |
++--------------------------------+-----------------------------------------+--------------------------------------------------------------+
+| | ``[enum Class.name]``        | ``See [enum Mesh.ArrayType].``          | See :ref:`Mesh.ArrayType <enum_Mesh_ArrayType>`.             |
+| | Link to enum                 |                                         |                                                              |
++--------------------------------+-----------------------------------------+--------------------------------------------------------------+
+| | ``[member Class.name]``      | ``Get [member Node2D.scale].``          | Get :ref:`Node2D.scale <class_Node2D_property_scale>`.       |
+| | Link to member               |                                         |                                                              |
++--------------------------------+-----------------------------------------+--------------------------------------------------------------+
+| | ``[method Class.name]``      | ``Call [method Node3D.hide].``          | Call :ref:`Node3D.hide() <class_Node3D_method_hide>`.        |
+| | Link to method               |                                         |                                                              |
++--------------------------------+-----------------------------------------+--------------------------------------------------------------+
+| | ``[constructor Class.name]`` | ``Use [constructor Color.Color].``      | Use  :ref:`Color.Color <class_Color_constructor_Color>`.     |
+| | Link to built-in constructor |                                         |                                                              |
++--------------------------------+-----------------------------------------+--------------------------------------------------------------+
+| | ``[operator Class.name]``    | ``Use [operator Color.operator *].``    | Use  :ref:`Color.operator * <class_Color_operator_mul_int>`. |
+| | Link to built-in operator    |                                         |                                                              |
++--------------------------------+-----------------------------------------+--------------------------------------------------------------+
+| | ``[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.                                 |
+| | Parameter name (as code)     |                                         |                                                              |
++--------------------------------+-----------------------------------------+--------------------------------------------------------------+
 
 .. note::
 
@@ -169,51 +178,67 @@ For links to the same class, the class name is optional and can be omitted.
 Formatting text
 """""""""""""""
 
-+--------------------------------------+--------------------------------------+------------------------------+
-| 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 and Description            | Example                                      | Result                             |
++================================+==============================================+====================================+
+| | ``[br]``                     | | ``Line 1.[br]``                            | | Line 1.                          |
+| | Line break                   | | ``Line 2.``                                | | Line 2.                          |
++--------------------------------+----------------------------------------------+------------------------------------+
+| | ``[lb]`` ``[rb]``            | ``[lb]b[rb]text[lb]/b[rb]``                  | [b]text[/b]                        |
+| | ``[`` and ``]`` respectively |                                              |                                    |
++--------------------------------+----------------------------------------------+------------------------------------+
+| | ``[b]`` ``[/b]``             | ``Do [b]not[/b] call this method.``          | Do **not** call this method.       |
+| | Bold                         |                                              |                                    |
++--------------------------------+----------------------------------------------+------------------------------------+
+| | ``[i]`` ``[/i]``             | ``Returns the [i]global[/i] position.``      | Returns the *global* position.     |
+| | Italic                       |                                              |                                    |
++--------------------------------+----------------------------------------------+------------------------------------+
+| | ``[u]`` ``[/u]``             | ``[u]Always[/u] use this method.``           | .. raw:: html                      |
+| | Underline                    |                                              |                                    |
+|                                |                                              |     <u>Always</u> use this method. |
++--------------------------------+----------------------------------------------+------------------------------------+
+| | ``[s]`` ``[/s]``             | ``[s]Outdated information.[/s]``             | .. raw:: html                      |
+| | Strikethrough                |                                              |                                    |
+|                                |                                              |     <s>Outdated information.</s>   |
++--------------------------------+----------------------------------------------+------------------------------------+
+| | ``[url]`` ``[/url]``         | | ``[url]https://example.com[/url]``         | | https://example.com              |
+| | Hyperlink                    | | ``[url=https://example.com]Website[/url]`` | | `Website <https://example.com>`_ |
++--------------------------------+----------------------------------------------+------------------------------------+
+| | ``[center]`` ``[/center]``   | ``[center]2 + 2 = 4[/center]``               | .. raw:: html                      |
+| | Horizontal centering         |                                              |                                    |
+|                                |                                              |     <center>2 + 2 = 4</center>     |
++--------------------------------+----------------------------------------------+------------------------------------+
+| | ``[kbd]`` ``[/kbd]``         | ``Press [kbd]Ctrl + C[/kbd].``               | Press :kbd:`Ctrl + C`.             |
+| | Keyboard/mouse shortcut      |                                              |                                    |
++--------------------------------+----------------------------------------------+------------------------------------+
+| | ``[code]`` ``[/code]``       | ``Returns [code]true[/code].``               | Returns ``true``.                  |
+| | Inline code fragment         |                                              |                                    |
++--------------------------------+----------------------------------------------+------------------------------------+
+
+.. note::
+
+    1. Some supported tags like ``[color]`` and ``[font]`` are not listed here because they are not recommended in the engine documentation.
+    2. ``[kbd]`` disables BBCode until the parser encounters ``[/kbd]``.
+    3. ``[code]`` disables BBCode until the parser encounters ``[/code]``.
+
+Formatting code blocks
+""""""""""""""""""""""
+
+There are two options for formatting code blocks:
 
-+----------------------------------------+---------------------------------------+--------------------------+
-| 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       |                                       |                          |
-+----------------------------------------+---------------------------------------+--------------------------+
+1. Use ``[codeblock]`` if you want to add an example for a specific language.
+2. Use ``[codeblocks]``, ``[gdscript]``, and ``[csharp]`` if you want to add the same example for both languages, GDScript and C#.
+
+By default, ``[codeblock]`` highlights GDScript syntax. You can change it using
+the ``lang`` attribute. Currently supported options are:
+
+- ``[codeblock lang=text]`` disables syntax highlighting;
+- ``[codeblock lang=gdscript]`` highlights GDScript syntax;
+- ``[codeblock lang=csharp]`` highlights C# syntax (only in .NET version).
 
 .. note::
 
-    1. ``[code]`` disables BBCode until the parser encounters ``[/code]``.
-    2. ``[codeblock]`` disables BBCode until the parser encounters ``[/codeblock]``.
+    ``[codeblock]`` disables BBCode until the parser encounters ``[/codeblock]``.
 
 .. warning::
 
@@ -280,6 +305,9 @@ The above will display as:
         GD.Print(sprite.GetPos());
     }
 
+Formatting notes and warnings
+"""""""""""""""""""""""""""""
+
 To denote important information, add a paragraph starting with "[b]Note:[/b]" at
 the end of the description:
 
@@ -295,12 +323,33 @@ the end of the description:
 
     [b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.
 
-For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]".
-Notice the use of italics instead of bold:
+In all the paragraphs described above, make sure the punctuation is part of the
+BBCode tags for consistency.
+
+Marking API as deprecated/experimental
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: none
+To mark an API as deprecated or experimental, you need to add the corresponding XML attribute. The attribute value must be a message
+explaining why the API is not recommended (BBCode markup is supported) or an empty string (the default message will be used).
+If an API element is marked as deprecated/experimental, then it is considered documented even if the description is empty.
 
-    [i]Deprecated.[/i] This property has been replaced by [member other_property].
+.. code-block:: xml
 
-In all the paragraphs described above, make sure the punctuation is part of the
-BBCode tags for consistency.
+    <class name="Parallax2D" inherits="Node2D" experimental="This node is meant to replace [ParallaxBackground] and [ParallaxLayer]. The implementation may change in the future." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+        [...]
+    </class>
+
+    <constant name="RESPONSE_USE_PROXY" value="305" enum="ResponseCode" deprecated="Many clients ignore this response code for security reasons. It is also deprecated by the HTTP standard.">
+        HTTP status code [code]305 Use Proxy[/code].
+    </constant>
+
+    <member name="auto_translate" type="bool" setter="set_auto_translate" getter="is_auto_translating" deprecated="Use [member Node.auto_translate_mode] instead.">
+        Toggles if any text should automatically change to its translated version depending on the current locale.
+    </member>
+
+    <method name="get_method_call_mode" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_method] instead.">
+        <return type="int" enum="AnimationPlayer.AnimationMethodCallMode" />
+        <description>
+            Returns the call mode used for "Call Method" tracks.
+        </description>
+    </method>

tutorials/scripting/gdscript/gdscript_documentation_comments.rst

@@ -224,72 +224,106 @@ This can be especially useful for plugin and library creators.
 BBCode and class reference
 --------------------------
 
-The editor help window which renders the documentation supports :ref:`bbcode <doc_bbcode_in_richtextlabel>`.
-As a result it's possible to align and format the documentation. Color texts, images, fonts, tables,
-URLs, animation effects, etc. can be added with the :ref:`bbcode <doc_bbcode_in_richtextlabel>`.
-
 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>`.
+Note that this is slightly different from the ``RichTextLabel`` :ref:`BBCode <doc_bbcode_in_richtextlabel>`.
 
 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 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       |                                         |                                                                      |
-+--------------------------------------+-----------------------------------------+----------------------------------------------------------------------+
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| Tag and Description            | Example                                      | Result                                                       |
++================================+==============================================+==============================================================+
+| | ``[Class]``                  | ``Move the [Sprite2D].``                     | Move the :ref:`class_Sprite2D`.                              |
+| | Link to class                |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[annotation Class.name]``  | ``See [annotation @GDScript.@rpc].``         | See :ref:`@GDScript.@rpc <class_@GDScript_annotation_@rpc>`. |
+| | Link to annotation           |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[constant Class.name]``    | ``See [constant Color.RED].``                | See :ref:`Color.RED <class_Color_constant_RED>`.             |
+| | Link to constant             |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[enum Class.name]``        | ``See [enum Mesh.ArrayType].``               | See :ref:`Mesh.ArrayType <enum_Mesh_ArrayType>`.             |
+| | Link to enum                 |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[member Class.name]``      | ``Get [member Node2D.scale].``               | Get :ref:`Node2D.scale <class_Node2D_property_scale>`.       |
+| | Link to member (property)    |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[method Class.name]``      | ``Call [method Node3D.hide].``               | Call :ref:`Node3D.hide() <class_Node3D_method_hide>`.        |
+| | Link to method               |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[constructor Class.name]`` | ``Use [constructor Color.Color].``           | Use  :ref:`Color.Color <class_Color_constructor_Color>`.     |
+| | Link to built-in constructor |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[operator Class.name]``    | ``Use [operator Color.operator *].``         | Use  :ref:`Color.operator * <class_Color_operator_mul_int>`. |
+| | Link to built-in operator    |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[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.                                 |
+| | Parameter name (as code)     |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[br]``                     | | ``Line 1.[br]``                            | | Line 1.                                                    |
+| | Line break                   | | ``Line 2.``                                | | Line 2.                                                    |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[lb]`` ``[rb]``            | ``[lb]b[rb]text[lb]/b[rb]``                  | [b]text[/b]                                                  |
+| | ``[`` and ``]`` respectively |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[b]`` ``[/b]``             | ``Do [b]not[/b] call this method.``          | Do **not** call this method.                                 |
+| | Bold                         |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[i]`` ``[/i]``             | ``Returns the [i]global[/i] position.``      | Returns the *global* position.                               |
+| | Italic                       |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[u]`` ``[/u]``             | ``[u]Always[/u] use this method.``           | .. raw:: html                                                |
+| | Underline                    |                                              |                                                              |
+|                                |                                              |     <u>Always</u> use this method.                           |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[s]`` ``[/s]``             | ``[s]Outdated information.[/s]``             | .. raw:: html                                                |
+| | Strikethrough                |                                              |                                                              |
+|                                |                                              |     <s>Outdated information.</s>                             |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[color]`` ``[/color]``     | ``[color=red]Error![/color]``                | .. raw:: html                                                |
+| | Color                        |                                              |                                                              |
+|                                |                                              |     <span style="color:red;">Error!</span>                   |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[font]`` ``[/font]``       | ``[font=res://mono.ttf]LICENSE[/font]``      | .. raw:: html                                                |
+| | Font                         |                                              |                                                              |
+|                                |                                              |     <span style="font-family:monospace;">LICENSE</span>      |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[img]`` ``[/img]``         | ``[img width=32]res://icon.svg[/img]``       | .. image:: img/icon.svg                                      |
+| | Image                        |                                              |    :width: 32 px                                             |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[url]`` ``[/url]``         | | ``[url]https://example.com[/url]``         | | https://example.com                                        |
+| | Hyperlink                    | | ``[url=https://example.com]Website[/url]`` | | `Website <https://example.com>`_                           |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[center]`` ``[/center]``   | ``[center]2 + 2 = 4[/center]``               | .. raw:: html                                                |
+| | Horizontal centering         |                                              |                                                              |
+|                                |                                              |     <center>2 + 2 = 4</center>                               |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[kbd]`` ``[/kbd]``         | ``Press [kbd]Ctrl + C[/kbd].``               | Press :kbd:`Ctrl + C`.                                       |
+| | Keyboard/mouse shortcut      |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[code]`` ``[/code]``       | ``Returns [code]true[/code].``               | Returns ``true``.                                            |
+| | Inline code fragment         |                                              |                                                              |
++--------------------------------+----------------------------------------------+--------------------------------------------------------------+
+| | ``[codeblock]``              | *See below.*                                 | *See below.*                                                 |
+| | ``[/codeblock]``             |                                              |                                                              |
+| | Multiline code 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]``.
+    2. ``[kbd]`` disables BBCode until the parser encounters ``[/kbd]``.
+    3. ``[code]`` disables BBCode until the parser encounters ``[/code]``.
+    4. ``[codeblock]`` disables BBCode until the parser encounters ``[/codeblock]``.
 
 .. warning::
 
@@ -310,3 +344,10 @@ Here's the list of available tags:
     ## [/codeblock]
     func do_something():
         pass
+
+By default, ``[codeblock]`` highlights GDScript syntax. You can change it using
+the ``lang`` attribute. Currently supported options are:
+
+- ``[codeblock lang=text]`` disables syntax highlighting;
+- ``[codeblock lang=gdscript]`` highlights GDScript syntax;
+- ``[codeblock lang=csharp]`` highlights C# syntax (only in .NET version).