From 6fac7f0d8d02c4f9e1eeadbe0b152f7ae158ccfc Mon Sep 17 00:00:00 2001 From: Thakee Nathees Date: Tue, 11 Aug 2020 18:52:22 +0530 Subject: [PATCH] documentation for the GDScript documentation comments (thanks @baloonpopper and @Calinou for the nitpicks) Co-ayuthored-by: balloonpopper<5151242+balloonpopper@users.noreply.github.com> Co-authored-by: Hugo Locurcio --- .../gdscript_documentation_comments.rst | 217 ++++++++++++++++++ tutorials/scripting/gdscript/index.rst | 1 + 2 files changed, 218 insertions(+) create mode 100644 tutorials/scripting/gdscript/gdscript_documentation_comments.rst diff --git a/tutorials/scripting/gdscript/gdscript_documentation_comments.rst b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst new file mode 100644 index 00000000000..90d478d27ac --- /dev/null +++ b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst @@ -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 `. + +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 `. +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 `. + +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 `. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide]. | See :ref:`hide `. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [member membername] | Link to a member in this class | Get [member scale]. | Get :ref:`scale `. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [member Class.membername] | Link to another class's member | Get [member Node2D.scale]. | Get :ref:`scale `. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [signal signalname] | Link to a signal in this class | Emit [signal renamed]. | Emit :ref:`renamed `. | ++---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+ +| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed]. | Emit :ref:`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 diff --git a/tutorials/scripting/gdscript/index.rst b/tutorials/scripting/gdscript/index.rst index c0f149e554c..fa0ad60ab29 100644 --- a/tutorials/scripting/gdscript/index.rst +++ b/tutorials/scripting/gdscript/index.rst @@ -8,6 +8,7 @@ GDScript gdscript_basics gdscript_advanced gdscript_exports + gdscript_documentation_comments gdscript_styleguide static_typing warning_system