godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-05 22:09:56 +03:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Update class reference and doc comment markup documentation
This commit is contained in:
Max Hilbrunner
2024-05-07 11:27:26 +02:00
committed by GitHub
parent ebbd945a84 c89b0e6ab3
commit 4e216fc5fc
3 changed files with 221 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

149
tutorials/scripting/gdscript/gdscript_documentation_comments.rst
View File

@@ -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).

1
tutorials/scripting/gdscript/img/icon.svg Normal file
View File

@@ -0,0 +1 @@
<svg height="128" width="128" xmlns="http://www.w3.org/2000/svg"><g transform="translate(32 32)"><path d="m-16-32c-8.86 0-16 7.13-16 15.99v95.98c0 8.86 7.13 15.99 16 15.99h96c8.86 0 16-7.13 16-15.99v-95.98c0-8.85-7.14-15.99-16-15.99z" fill="#363d52"/><path d="m-16-32c-8.86 0-16 7.13-16 15.99v95.98c0 8.86 7.13 15.99 16 15.99h96c8.86 0 16-7.13 16-15.99v-95.98c0-8.85-7.14-15.99-16-15.99zm0 4h96c6.64 0 12 5.35 12 11.99v95.98c0 6.64-5.35 11.99-12 11.99h-96c-6.64 0-12-5.35-12-11.99v-95.98c0-6.64 5.36-11.99 12-11.99z" fill-opacity=".4"/></g><g stroke-width="9.92746" transform="matrix(.10073078 0 0 .10073078 12.425923 2.256365)"><path d="m0 0s-.325 1.994-.515 1.976l-36.182-3.491c-2.879-.278-5.115-2.574-5.317-5.459l-.994-14.247-27.992-1.997-1.904 12.912c-.424 2.872-2.932 5.037-5.835 5.037h-38.188c-2.902 0-5.41-2.165-5.834-5.037l-1.905-12.912-27.992 1.997-.994 14.247c-.202 2.886-2.438 5.182-5.317 5.46l-36.2 3.49c-.187.018-.324-1.978-.511-1.978l-.049-7.83 30.658-4.944 1.004-14.374c.203-2.91 2.551-5.263 5.463-5.472l38.551-2.75c.146-.01.29-.016.434-.016 2.897 0 5.401 2.166 5.825 5.038l1.959 13.286h28.005l1.959-13.286c.423-2.871 2.93-5.037 5.831-5.037.142 0 .284.005.423.015l38.556 2.75c2.911.209 5.26 2.562 5.463 5.472l1.003 14.374 30.645 4.966z" fill="#fff" transform="matrix(4.162611 0 0 -4.162611 919.24059 771.67186)"/><path d="m0 0v-47.514-6.035-5.492c.108-.001.216-.005.323-.015l36.196-3.49c1.896-.183 3.382-1.709 3.514-3.609l1.116-15.978 31.574-2.253 2.175 14.747c.282 1.912 1.922 3.329 3.856 3.329h38.188c1.933 0 3.573-1.417 3.855-3.329l2.175-14.747 31.575 2.253 1.115 15.978c.133 1.9 1.618 3.425 3.514 3.609l36.182 3.49c.107.01.214.014.322.015v4.711l.015.005v54.325c5.09692 6.4164715 9.92323 13.494208 13.621 19.449-5.651 9.62-12.575 18.217-19.976 26.182-6.864-3.455-13.531-7.369-19.828-11.534-3.151 3.132-6.7 5.694-10.186 8.372-3.425 2.751-7.285 4.768-10.946 7.118 1.09 8.117 1.629 16.108 1.846 24.448-9.446 4.754-19.519 7.906-29.708 10.17-4.068-6.837-7.788-14.241-11.028-21.479-3.842.642-7.702.88-11.567.926v.006c-.027 0-.052-.006-.075-.006-.024 0-.049.006-.073.006v-.006c-3.872-.046-7.729-.284-11.572-.926-3.238 7.238-6.956 14.642-11.03 21.479-10.184-2.264-20.258-5.416-29.703-10.17.216-8.34.755-16.331 1.848-24.448-3.668-2.35-7.523-4.367-10.949-7.118-3.481-2.678-7.036-5.24-10.188-8.372-6.297 4.165-12.962 8.079-19.828 11.534-7.401-7.965-14.321-16.562-19.974-26.182 4.4426579-6.973692 9.2079702-13.9828876 13.621-19.449z" fill="#478cbf" transform="matrix(4.162611 0 0 -4.162611 104.69892 525.90697)"/><path d="m0 0-1.121-16.063c-.135-1.936-1.675-3.477-3.611-3.616l-38.555-2.751c-.094-.007-.188-.01-.281-.01-1.916 0-3.569 1.406-3.852 3.33l-2.211 14.994h-31.459l-2.211-14.994c-.297-2.018-2.101-3.469-4.133-3.32l-38.555 2.751c-1.936.139-3.476 1.68-3.611 3.616l-1.121 16.063-32.547 3.138c.015-3.498.06-7.33.06-8.093 0-34.374 43.605-50.896 97.781-51.086h.066.067c54.176.19 97.766 16.712 97.766 51.086 0 .777.047 4.593.063 8.093z" fill="#478cbf" transform="matrix(4.162611 0 0 -4.162611 784.07144 817.24284)"/><path d="m0 0c0-12.052-9.765-21.815-21.813-21.815-12.042 0-21.81 9.763-21.81 21.815 0 12.044 9.768 21.802 21.81 21.802 12.048 0 21.813-9.758 21.813-21.802" fill="#fff" transform="matrix(4.162611 0 0 -4.162611 389.21484 625.67104)"/><path d="m0 0c0-7.994-6.479-14.473-14.479-14.473-7.996 0-14.479 6.479-14.479 14.473s6.483 14.479 14.479 14.479c8 0 14.479-6.485 14.479-14.479" fill="#414042" transform="matrix(4.162611 0 0 -4.162611 367.36686 631.05679)"/><path d="m0 0c-3.878 0-7.021 2.858-7.021 6.381v20.081c0 3.52 3.143 6.381 7.021 6.381s7.028-2.861 7.028-6.381v-20.081c0-3.523-3.15-6.381-7.028-6.381" fill="#fff" transform="matrix(4.162611 0 0 -4.162611 511.99336 724.73954)"/><path d="m0 0c0-12.052 9.765-21.815 21.815-21.815 12.041 0 21.808 9.763 21.808 21.815 0 12.044-9.767 21.802-21.808 21.802-12.05 0-21.815-9.758-21.815-21.802" fill="#fff" transform="matrix(4.162611 0 0 -4.162611 634.78706 625.67104)"/><path d="m0 0c0-7.994 6.477-14.473 14.471-14.473 8.002 0 14.479 6.479 14.479 14.473s-6.477 14.479-14.479 14.479c-7.994 0-14.471-6.485-14.471-14.479" fill="#414042" transform="matrix(4.162611 0 0 -4.162611 656.64056 631.05679)"/></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 4.1 KiB