-
-
Notifications
You must be signed in to change notification settings - Fork 3.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #3892 from ThakeeNathees/gdscript-documentation-co…
…mments Documentation for the GDScript documentation comments
- Loading branch information
Showing
2 changed files
with
218 additions
and
0 deletions.
There are no files selected for viewing
217 changes: 217 additions & 0 deletions
217
tutorials/scripting/gdscript/gdscript_documentation_comments.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,217 @@ | ||
.. _doc_gdscript_documentation_comments: | ||
|
||
GDScript documentation comments | ||
=============================== | ||
|
||
In GDScript, comments can be used to document your code and add description to the | ||
members of a script. There are two differences between a normal comment and a documentation | ||
comment. Firstly, a documentation comment should start with double hash symbols | ||
``##``. Secondly, it must immediately precede a script member, or for script descriptions, | ||
be placed at the top of the script. If an exported variable is documented, | ||
its description is used as a tooltip in the editor. This documentation can be | ||
generated as XML files by the editor. | ||
|
||
Documenting a script | ||
-------------------- | ||
|
||
Comments documenting a script must come before any member documentation. A | ||
suggested format for script documentation can be divided into three parts. | ||
|
||
- A brief description of the script. | ||
- Detailed description. | ||
- Tutorials. | ||
|
||
To separate these from each other, the documentation comments use special tags. | ||
The tag must be at the beginning of a line (ignoring preceding white space) and has | ||
the format ``@``, followed by the keyword and finishing with a colon. | ||
|
||
Tags | ||
~~~~ | ||
|
||
+-------------------+--------------------------------------------------------+ | ||
| Brief description | No tag and lives at the very beginning of | | ||
| | the documentation section. | | ||
+-------------------+--------------------------------------------------------+ | ||
| Description | ``@desc:`` | | ||
| | | | ||
+-------------------+--------------------------------------------------------+ | ||
| Tutorial | ``@tutorial[( The Title Here )]:`` | | ||
| | | | ||
+-------------------+--------------------------------------------------------+ | ||
|
||
**Example:** | ||
|
||
:: | ||
|
||
extends Node2D | ||
## | ||
## A brief description of your script. | ||
## | ||
## @desc: | ||
## A more detailed description of the script. | ||
## | ||
## @tutorial: http://the/tutorial1/url.com | ||
## @tutorial(Tutorial2): http://the/tutorial2/url.com | ||
## | ||
|
||
.. warning:: If there is any space in between the tag name and colon, for example | ||
``@desc :``, it won't treated as a valid tag and will be ignored. | ||
|
||
|
||
.. note:: When the description spans multiple lines, the preceding and trailing white | ||
spaces will be stripped and joined with a single space. To preserve the line | ||
break (or any other alignment), use | ||
:ref:`BBCode <doc_bbcode_in_richtextlabel>`. | ||
|
||
Documenting script members | ||
-------------------------- | ||
|
||
Documentation of a script member must immediately precede the member or its | ||
annotations if it has any. The exception to this is enum values whose description should | ||
be on the same line as the enum for readability. | ||
The description can have more than one line but every line must start | ||
with the double hash symbol ``##`` to be considered as part of the documentation. | ||
The script documentation will update in the editor help window every time the | ||
script is updated. If any member variable or function name starts with an | ||
underscore it will be treated as private. It will not appear in the documentation and | ||
will be ignored in the help window. | ||
|
||
Members that are applicable for the documentation: | ||
|
||
- Inner class | ||
- Constant | ||
- Function | ||
- Signal | ||
- Variable | ||
- Enum | ||
- Enum value | ||
|
||
Examples | ||
-------- | ||
|
||
:: | ||
|
||
extends Node2D | ||
## | ||
## A brief description of your script. | ||
## | ||
## @desc: | ||
## The description of the script, what it | ||
## can do, and any further detail. | ||
## | ||
## @tutorial: http://the/tutorial1/url.com | ||
## @tutorial(Tutorial2): http://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. | ||
@export | ||
@onready | ||
var v3 := some_func() | ||
## The description of a constant. | ||
const GRAVITY = 9.8 | ||
## The description of a signal. | ||
signal my_signal | ||
## This is a description of the below enums. Note below that | ||
## the enum values are documented on the same line as the enum. | ||
enum Direction { | ||
UP = 0, ## Direction up. | ||
DOWN = 1, ## Direction down. | ||
LEFT = 2, ## Direction left. | ||
RIGHT = 3, ## Direction right. | ||
} | ||
## 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. | ||
## | ||
## @desc: The same rules apply apply here. The documentation must | ||
## immediately precede the class definition. | ||
## | ||
## @tutorial: http://the/tutorial/url.com | ||
class Inner: | ||
## Inner class variable v4. | ||
var v4 | ||
## Inner class function fn. | ||
func fn(): pass | ||
|
||
|
||
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. Here's the list of available tags: | ||
|
||
+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ | ||
| Tag | Effect | Usage | Result | | ||
+===========================+================================+===================================+===================================================+ | ||
| [Class] | Link a class | Move the [Sprite]. | Move the :ref:`class_sprite`. | | ||
+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ | ||
| [method methodname] | Link to a method in this class | Call [method hide]. | See :ref:`hide <class_spatial_method_hide>`. | | ||
+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ | ||
| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide]. | See :ref:`hide <class_spatial_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>`. | | ||
+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ | ||
| [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). | ||
|
||
:: | ||
|
||
## The do_something method for this plugin. before useing the | ||
## method you first have to initialize [MyPlugin]. | ||
## see : [method initialize] | ||
## [color=yellow]Warning:[/color] always [method clean] after use. | ||
## Usage: | ||
## [codeblock] | ||
## func _ready(): | ||
## the_plugin.initialize() | ||
## the_plugin.do_something() | ||
## the_plugin.clean() | ||
## [/codeblock] | ||
func do_something(): | ||
pass |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters