documentation for the GDScript documentation comments

getting_started/scripting/gdscript/gdscript_documentation_comments.rst

@@ -0,0 +1,221 @@
+.. _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. The difference between a normal comment and a documentation
+comment is that the documentation comment should starts with double hash symbols
+``##`` and it  must immediately precede a script member or the top of the script
+if the description is about the script. If an exported variable is documented,
+it's description is used as a tooltip in the editor. These documentations can be
+generated as XML files by the editor.
+
+Documenting a script
+--------------------
+
+Documentation of a script must comes before any other member documentations. The
+script documentation could be divided into three parts.
+
+- A brief description about the script
+- Description of the script
+- Tutorials
+
+To separate these from each other, the documentation comment use special tags
+inside the comments with the tag name followed by an at sign ``@`` and
+immediately before a colon also they must be at the beginning of a line ignoring
+the preceding white spaces.
+
+Tags
+~~~~
+
++-------------------+--------------------------------------------------------+
+| Brief description | No tag and the brief must be at the very beginning of  |
+|                   | the documentation section.                             |
++-------------------+--------------------------------------------------------+
+| Description       | ``@desc:``                                             |
+|                   |                                                        |
++-------------------+--------------------------------------------------------+
+| Tutorial          | ``@tutorial[( The Title Here )]:``                     |
+|                   |                                                        |
++-------------------+--------------------------------------------------------+
+
+**Example:**
+
+::
+
+    extends Node2D
+	
+    ## 
+    ## A brief description about your script.
+    ##
+    ## @desc:
+    ##     The description about the script, what it
+    ##     can do, how to do that and everything.
+    ## 
+    ## @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 ``@desc  :``
+			 it won't treated as a valid tag and ignored.
+
+
+.. note:: When the description is multi line the preceding and trailing white
+		  spaces will be striped and joined with a single space. If the line 
+		  break (or any other alignment) is intended use
+		  :ref:`bbcode <doc_bbcode_in_richtextlabel>`.
+
+
+Documenting script members
+--------------------------
+
+Documentation of a script member must immediately precede the member or it's
+annotations if it has any **except for enum values** which's description is should
+be at the the same line as it is. It's designed like this for a better readability
+and look. The description could have more than one line but every line must starts
+with the double hash symbol ``##`` to be considered as it's part of the documentation.
+The script documentation will update in the editor help window every time the
+script updated and if any member variable or function name starts with an
+underscore and undocumented it'll treated as private for the documentation and
+ignored in the 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 about your script.
+    ##
+    ## @desc:
+    ##     The description about the script, what it
+    ##     can do, how to do that and everything.
+    ## 
+    ## @tutorial:            http://the/tutorial1/url.com
+    ## @tutorial(Tutorial2): http://the/tutorial2/url.com
+    ##
+    
+    ## the description about the variable v1
+    var v1
+    
+    ## multi line description about the variable v2. the type
+    ## information will be extracted below for the documentation
+    var v2: int
+    
+    ## if there are any annotation the member has, then it should
+    ## immediately precede them.
+    @export
+    @onready
+    var v3 := some_func()
+    
+    ## the description of a constant
+    const GRAVITY = 9.8
+	
+    ## the description of a signal
+    signal my_signal
+    
+    ## it's the enum description and see below the exception for 
+    ## the enum values which are documented on the same line.
+    enum Direction {
+        UP    = 0,  ## direction up
+        DOWN  = 1,  ## direction down
+        LEFT  = 2,  ## direction left
+        RIGHT = 3,  ## direction right
+    }
+    
+    ## since the below function is documented even it's name starts with
+    ## an underscore, it'll be updated in the editor.
+    func _fn(p1:int, p2:String) -> int:
+        return 0
+    
+    # the below function isn't documented and starts with an underscore name
+    # so this will treated as private and will not be updated in the editor.
+    func _internal() -> void:
+        pass
+    
+    ## About the inner class.
+    ## 
+    ## @desc: same rules like script description applies here, and It 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>`,
+so it's possible to align and format the documentations and in addition color texts, images, fonts, tables,
+urls, animation effects, etc. could 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 methodmethod you first have to initialize.
+    ## see : [method initialize]
+    ## Usage:
+    ##     [codeblock]
+    ##     func _ready():
+    ##         the_plugin.initialize()
+    ##         the_plugin.do_something()
+    ##         the_plugin.clean()
+    ##     [/codeblock]
+    func do_something():
+        pass
+
+

getting_started/scripting/gdscript/index.rst

@@ -8,6 +8,7 @@ GDScript
    gdscript_basics
    gdscript_advanced
    gdscript_exports
+   gdscript_documentation_comments
    gdscript_styleguide
    static_typing
    warning_system