Skip to content

Commit d8e71f7

Browse files
dalexeevdalexeev
committed
Update info about BBCode in doc comments and Class Reference
1 parent d72080c commit d8e71f7

File tree

3 files changed

+253
-194
lines changed

3 files changed

+253
-194
lines changed

‎contributing/documentation/class_reference_primer.rst‎

Lines changed: 79 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -134,62 +134,93 @@ Linking
134134
Whenever you link to a member of another class, you need to specify the class name.
135135
For links to the same class, the class name is optional and can be omitted.
136136

137-
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
138-
| Tag | Effect | Usage | Result |
139-
+=========================+=================================================+=========================================+=============================================================================+
140-
| [Class] | Link to class ``Class`` | Move the [Sprite2D]. | Move the :ref:`class_Sprite2D`. |
141-
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
142-
| [annotation Class.name] | Link to annotation ``name`` in class ``Class``, | See [annotation @GDScript.@export]. | See :ref:`@GDScript.@export<class_@GDScript_annotation_@export>`. |
143-
| | many default annotations are in ``@GDScript`` | | |
144-
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
145-
| [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>`. |
146-
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
147-
| [enum Class.name] | Link to enum ``name`` in class ``Class`` | See [enum Mesh.ArrayType]. | See :ref:`ArrayType<enum_Mesh_ArrayType>`. |
148-
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
149-
| [method Class.name] | Link to method ``name`` in class ``Class`` | Call [method Node3D.hide]. | Call :ref:`hide<class_Node3D_method_hide>`. |
150-
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
151-
| [member Class.name] | Link to member ``name`` in class ``Class`` | Get [member Node2D.scale]. | Get :ref:`scale<class_Node2D_property_scale>`. |
152-
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
153-
| [signal Class.name] | Link to signal ``name`` in class ``Class`` | Emit [signal Node.renamed]. | Emit :ref:`renamed<class_Node_signal_renamed>`. |
154-
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
155-
| [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>`. |
156-
+-------------------------+-------------------------------------------------+-----------------------------------------+-----------------------------------------------------------------------------+
137+
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
138+
| Tag and Description | Example | Result |
139+
+===============================+=========================================+======================================================================+
140+
| | ``[Class]`` | ``Move the [Sprite2D].`` | Move the :ref:`class_Sprite2D`. |
141+
| | Link to class | | |
142+
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
143+
| | ``[annotation Class.name]`` | ``See [annotation @GDScript.@export].`` | See :ref:`@GDScript.@export <class_@GDScript_annotation_@export>`. |
144+
| | Link to annotation | | |
145+
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
146+
| | ``[constant Class.name]`` | ``See [constant @GlobalScope.KEY_F1].`` | See :ref:`@GlobalScope.KEY_F1 <class_@GlobalScope_constant_KEY_F1>`. |
147+
| | Link to constant | | |
148+
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
149+
| | ``[enum Class.name]`` | ``See [enum Mesh.ArrayType].`` | See :ref:`Mesh.ArrayType <enum_Mesh_ArrayType>`. |
150+
| | Link to enum | | |
151+
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
152+
| | ``[method Class.name]`` | ``Call [method Node3D.hide].`` | Call :ref:`Node3D.hide() <class_Node3D_method_hide>`. |
153+
| | Link to method | | |
154+
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
155+
| | ``[member Class.name]`` | ``Get [member Node2D.scale].`` | Get :ref:`Node2D.scale <class_Node2D_property_scale>`. |
156+
| | Link to member | | |
157+
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
158+
| | ``[signal Class.name]`` | ``Emit [signal Node.renamed].`` | Emit :ref:`Node.renamed <class_Node_signal_renamed>`. |
159+
| | Link to signal | | |
160+
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
161+
| | ``[theme_item Class.name]`` | ``See [theme_item Label.font].`` | See :ref:`Label.font <class_Label_theme_font_font>`. |
162+
| | Link to theme item | | |
163+
+-------------------------------+-----------------------------------------+----------------------------------------------------------------------+
164+
165+
.. note::
166+
167+
Currently only :ref:`class_@GDScript` has annotations.
157168

158169
Formatting text
159170
"""""""""""""""
160171

161-
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
162-
| Tag | Effect | Usage | Result |
163-
+============================+=====================================================+=====================================+===================================================================+
164-
| [param name] | Formats a parameter name (as code) | Takes [param size] for the size. | Takes ``size`` for the size. |
165-
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
166-
| [b] [/b] | Bold | Some [b]bold[/b] text. | Some **bold** text. |
167-
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
168-
| [i] [/i] | Italic | Some [i]italic[/i] text. | Some *italic* text. |
169-
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
170-
| [kbd] [/kbd] | Keyboard/mouse shortcut | Some [kbd]Ctrl + C[/kbd] key. | Some :kbd:`Ctrl + C` key. |
171-
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
172+
+--------------------------------------+--------------------------------------+------------------------------+
173+
| Tag and Description | Example | Result |
174+
+======================================+======================================+==============================+
175+
| | ``[param name]`` | ``Takes [param size] for the size.`` | Takes ``size`` for the size. |
176+
| | Formats a parameter name (as code) | | |
177+
+--------------------------------------+--------------------------------------+------------------------------+
178+
| | ``[br]`` | | ``Line 1.[br]`` | | Line 1. |
179+
| | Line break | | ``Line 2.`` | | Line 2. |
180+
+--------------------------------------+--------------------------------------+------------------------------+
181+
| | ``[b]`` ``[/b]`` | ``Some [b]bold[/b] text.`` | Some **bold** text. |
182+
| | Bold | | |
183+
+--------------------------------------+--------------------------------------+------------------------------+
184+
| | ``[i]`` ``[/i]`` | ``Some [i]italic[/i] text.`` | Some *italic* text. |
185+
| | Italic | | |
186+
+--------------------------------------+--------------------------------------+------------------------------+
187+
| | ``[kbd]`` ``[/kbd]`` | ``Some [kbd]Ctrl + C[/kbd] key.`` | Some :kbd:`Ctrl + C` key. |
188+
| | Keyboard/mouse shortcut | | |
189+
+--------------------------------------+--------------------------------------+------------------------------+
172190

173191
Formatting code
174192
"""""""""""""""
175193

176-
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
177-
| Tag | Effect | Usage | Result |
178-
+============================+=====================================================+=====================================+===================================================================+
179-
| [code] [/code] | Monospace | Some [code]monospace[/code] text. | Some ``monospace`` text. |
180-
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
181-
| [codeblock] [/codeblock] | Multiline preformatted block | *See below.* | *See below.* |
182-
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
183-
| [codeblocks] [/codeblocks] | [codeblock] for multiple languages | *See below.* | *See below.* |
184-
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
185-
| [gdscript] [/gdscript] | GDScript codeblock tab in codeblocks | *See below.* | *See below.* |
186-
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
187-
| [csharp] [/csharp] | C# codeblock tab in codeblocks | *See below.* | *See below.* |
188-
+----------------------------+-----------------------------------------------------+-------------------------------------+-------------------------------------------------------------------+
189-
190-
Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``,
191-
always use **four spaces** for indentation. The parser will delete tabs. For
192-
example:
194+
+----------------------------------------+---------------------------------------+--------------------------+
195+
| Tag and Description | Example | Result |
196+
+========================================+=======================================+==========================+
197+
| | ``[code]`` ``[/code]`` | ``Some [code]monospace[/code] text.`` | Some ``monospace`` text. |
198+
| | Monospace | | |
199+
+----------------------------------------+---------------------------------------+--------------------------+
200+
| | ``[codeblock]`` ``[/codeblock]`` | *See below.* | *See below.* |
201+
| | Multiline preformatted block | | |
202+
+----------------------------------------+---------------------------------------+--------------------------+
203+
| | ``[codeblocks]`` ``[/codeblocks]`` | *See below.* | *See below.* |
204+
| | Codeblock for multiple languages | | |
205+
+----------------------------------------+---------------------------------------+--------------------------+
206+
| | ``[gdscript]`` ``[/gdscript]`` | *See below.* | *See below.* |
207+
| | GDScript codeblock tab in codeblocks | | |
208+
+----------------------------------------+---------------------------------------+--------------------------+
209+
| | ``[csharp]`` ``[/csharp]`` | *See below.* | *See below.* |
210+
| | C# codeblock tab in codeblocks | | |
211+
+----------------------------------------+---------------------------------------+--------------------------+
212+
213+
.. note::
214+
215+
1. ``[code]`` disables BBCode until the parser encounters ``[/code]``.
216+
2. ``[codeblock]`` disables BBCode until the parser encounters ``[/codeblock]``.
217+
218+
.. warning::
219+
220+
Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``,
221+
always use **four spaces** for indentation. The parser will delete tabs.
222+
223+
For example:
193224

194225
.. code-block:: none
195226

0 commit comments

Comments
 (0)