gdscript_documentation_comments.rst 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364
  1. .. _doc_gdscript_documentation_comments:
  2. GDScript documentation comments
  3. ===============================
  4. In GDScript, comments can be used to document your code and add descriptions to the
  5. members of a script. There are two differences between a normal comment and a documentation
  6. comment. Firstly, a documentation comment should start with double hash symbols
  7. ``##``. Secondly, it must immediately precede a script member, or for script descriptions,
  8. be placed at the top of the script. If an exported variable is documented,
  9. its description is used as a tooltip in the editor. This documentation can be
  10. generated as XML files by the editor.
  11. Documenting a script
  12. --------------------
  13. Comments documenting a script must come before any member documentation. A
  14. suggested format for script documentation can be divided into three parts.
  15. - A brief description of the script.
  16. - Detailed description.
  17. - Tutorials and deprecated/experimental marks.
  18. To separate these from each other, the documentation comments use special tags.
  19. The tag must be at the beginning of a line (ignoring preceding white space)
  20. and must have the format ``@``, followed by the keyword.
  21. Tags
  22. ~~~~
  23. +-------------------+--------------------------------------------------------+
  24. | Brief description | No tag. Lives at the very beginning of |
  25. | | the documentation section. |
  26. +-------------------+--------------------------------------------------------+
  27. | Description | No tag. Use one blank line to separate the description |
  28. | | from the brief. |
  29. +-------------------+--------------------------------------------------------+
  30. | Tutorial | | ``@tutorial: https://example.com`` |
  31. | | | ``@tutorial(The Title Here): https://example.com`` |
  32. +-------------------+--------------------------------------------------------+
  33. | Deprecated | | ``@deprecated`` |
  34. | | | ``@deprecated: Use [AnotherClass] instead.`` |
  35. +-------------------+--------------------------------------------------------+
  36. | Experimental | | ``@experimental`` |
  37. | | | ``@experimental: This class is unstable.`` |
  38. +-------------------+--------------------------------------------------------+
  39. For example:
  40. ::
  41. extends Node2D
  42. ## A brief description of the class's role and functionality.
  43. ##
  44. ## The description of the script, what it can do,
  45. ## and any further detail.
  46. ##
  47. ## @tutorial: https://example.com/tutorial_1
  48. ## @tutorial(Tutorial 2): https://example.com/tutorial_2
  49. ## @experimental
  50. .. warning::
  51. If there is any space in between the tag name and colon, for example
  52. ``@tutorial :``, it won't be treated as a valid tag and will be ignored.
  53. .. note::
  54. When the description spans multiple lines, the preceding and trailing white
  55. spaces will be stripped and joined with a single space. To preserve the line
  56. break use ``[br]``. See also `BBCode and class reference`_ below.
  57. Documenting script members
  58. --------------------------
  59. Members that are applicable for documentation:
  60. - Signal
  61. - Enum
  62. - Enum value
  63. - Constant
  64. - Variable
  65. - Function
  66. - Inner class
  67. Documentation of a script member must immediately precede the member or its annotations
  68. if it has any. The description can have more than one line but every line must start with
  69. the double hash symbol ``##`` to be considered as part of the documentation.
  70. Tags
  71. ~~~~
  72. +--------------+--------------------------------------------------+
  73. | Description | No tag. |
  74. +--------------+--------------------------------------------------+
  75. | Deprecated | | ``@deprecated`` |
  76. | | | ``@deprecated: Use [member another] instead.`` |
  77. +--------------+--------------------------------------------------+
  78. | Experimental | | ``@experimental`` |
  79. | | | ``@experimental: This method is incomplete.`` |
  80. +--------------+--------------------------------------------------+
  81. For example:
  82. ::
  83. ## The description of the variable.
  84. ## @deprecated: Use [member other_var] instead.
  85. var my_var
  86. Alternatively, you can use inline documentation comments:
  87. ::
  88. signal my_signal ## My signal.
  89. enum MyEnum { ## My enum.
  90. VALUE_A = 0, ## Value A.
  91. VALUE_B = 1, ## Value B.
  92. }
  93. const MY_CONST = 1 ## My constant.
  94. var my_var ## My variable.
  95. func my_func(): ## My func.
  96. pass
  97. class MyClass: ## My class.
  98. pass
  99. The script documentation will update in the editor help window every time the script is updated.
  100. If any member variable or function name starts with an underscore, it will be treated as private.
  101. It will not appear in the documentation and will be ignored in the help window.
  102. Complete script example
  103. -----------------------
  104. ::
  105. extends Node2D
  106. ## A brief description of the class's role and functionality.
  107. ##
  108. ## The description of the script, what it can do,
  109. ## and any further detail.
  110. ##
  111. ## @tutorial: https://example.com/tutorial_1
  112. ## @tutorial(Tutorial 2): https://example.com/tutorial_2
  113. ## @experimental
  114. ## The description of a signal.
  115. signal my_signal
  116. ## This is a description of the below enum.
  117. enum Direction {
  118. ## Direction up.
  119. UP = 0,
  120. ## Direction down.
  121. DOWN = 1,
  122. ## Direction left.
  123. LEFT = 2,
  124. ## Direction right.
  125. RIGHT = 3,
  126. }
  127. ## The description of a constant.
  128. const GRAVITY = 9.8
  129. ## The description of the variable v1.
  130. var v1
  131. ## This is a multiline description of the variable v2.[br]
  132. ## The type information below will be extracted for the documentation.
  133. var v2: int
  134. ## If the member has any annotation, the annotation should
  135. ## immediately precede it.
  136. @export
  137. var v3 := some_func()
  138. ## As the following function is documented, even though its name starts with
  139. ## an underscore, it will appear in the help window.
  140. func _fn(p1: int, p2: String) -> int:
  141. return 0
  142. # The below function isn't documented and its name starts with an underscore
  143. # so it will treated as private and will not be shown in the help window.
  144. func _internal() -> void:
  145. pass
  146. ## Documenting an inner class.
  147. ##
  148. ## The same rules apply here. The documentation must
  149. ## immediately precede the class definition.
  150. ##
  151. ## @tutorial: https://example.com/tutorial
  152. ## @experimental
  153. class Inner:
  154. ## Inner class variable v4.
  155. var v4
  156. ## Inner class function fn.
  157. func fn(): pass
  158. ``@deprecated`` and ``@experimental`` tags
  159. ------------------------------------------
  160. You can mark a class or any of its members as deprecated or experimental.
  161. This will add the corresponding indicator in the built-in documentation viewer.
  162. Optionally, you can provide a short message explaining why the API is not recommended.
  163. This can be especially useful for plugin and library creators.
  164. .. image:: img/deprecated_and_experimental_tags.webp
  165. - **Deprecated** marks a non-recommended API that is subject to removal or incompatible change
  166. in a future major release. Usually the API is kept for backwards compatibility.
  167. - **Experimental** marks a new unstable API that may be changed or removed in the current
  168. major branch. Using this API is not recommended in production code.
  169. .. note::
  170. While technically you can use both ``@deprecated`` and ``@experimental`` tags on the same
  171. class/member, this is not recommended as it is against common conventions.
  172. .. _doc_gdscript_documentation_comments_bbcode_and_class_reference:
  173. BBCode and class reference
  174. --------------------------
  175. Godot's class reference supports BBCode-like tags. They add nice formatting to the text which could also
  176. be used in the documentation. See also :ref:`class reference bbcode <doc_class_reference_bbcode>`.
  177. Note that this is slightly different from the ``RichTextLabel`` :ref:`BBCode <doc_bbcode_in_richtextlabel>`.
  178. Whenever you link to a member of another class, you need to specify the class name.
  179. For links to the same class, the class name is optional and can be omitted.
  180. Here's the list of available tags:
  181. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  182. | Tag and Description | Example | Result |
  183. +================================+==============================================+==============================================================+
  184. | | ``[Class]`` | ``Move the [Sprite2D].`` | Move the :ref:`class_Sprite2D`. |
  185. | | Link to class | | |
  186. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  187. | | ``[annotation Class.name]`` | ``See [annotation @GDScript.@rpc].`` | See :ref:`@GDScript.@rpc <class_@GDScript_annotation_@rpc>`. |
  188. | | Link to annotation | | |
  189. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  190. | | ``[constant Class.name]`` | ``See [constant Color.RED].`` | See :ref:`Color.RED <class_Color_constant_RED>`. |
  191. | | Link to constant | | |
  192. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  193. | | ``[enum Class.name]`` | ``See [enum Mesh.ArrayType].`` | See :ref:`Mesh.ArrayType <enum_Mesh_ArrayType>`. |
  194. | | Link to enum | | |
  195. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  196. | | ``[member Class.name]`` | ``Get [member Node2D.scale].`` | Get :ref:`Node2D.scale <class_Node2D_property_scale>`. |
  197. | | Link to member (property) | | |
  198. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  199. | | ``[method Class.name]`` | ``Call [method Node3D.hide].`` | Call :ref:`Node3D.hide() <class_Node3D_method_hide>`. |
  200. | | Link to method | | |
  201. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  202. | | ``[constructor Class.name]`` | ``Use [constructor Color.Color].`` | Use :ref:`Color.Color <class_Color_constructor_Color>`. |
  203. | | Link to built-in constructor | | |
  204. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  205. | | ``[operator Class.name]`` | ``Use [operator Color.operator *].`` | Use :ref:`Color.operator * <class_Color_operator_mul_int>`. |
  206. | | Link to built-in operator | | |
  207. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  208. | | ``[signal Class.name]`` | ``Emit [signal Node.renamed].`` | Emit :ref:`Node.renamed <class_Node_signal_renamed>`. |
  209. | | Link to signal | | |
  210. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  211. | | ``[theme_item Class.name]`` | ``See [theme_item Label.font].`` | See :ref:`Label.font <class_Label_theme_font_font>`. |
  212. | | Link to theme item | | |
  213. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  214. | | ``[param name]`` | ``Takes [param size] for the size.`` | Takes ``size`` for the size. |
  215. | | Parameter name (as code) | | |
  216. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  217. | | ``[br]`` | | ``Line 1.[br]`` | | Line 1. |
  218. | | Line break | | ``Line 2.`` | | Line 2. |
  219. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  220. | | ``[lb]`` ``[rb]`` | ``[lb]b[rb]text[lb]/b[rb]`` | [b]text[/b] |
  221. | | ``[`` and ``]`` respectively | | |
  222. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  223. | | ``[b]`` ``[/b]`` | ``Do [b]not[/b] call this method.`` | Do **not** call this method. |
  224. | | Bold | | |
  225. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  226. | | ``[i]`` ``[/i]`` | ``Returns the [i]global[/i] position.`` | Returns the *global* position. |
  227. | | Italic | | |
  228. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  229. | | ``[u]`` ``[/u]`` | ``[u]Always[/u] use this method.`` | .. raw:: html |
  230. | | Underline | | |
  231. | | | <u>Always</u> use this method. |
  232. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  233. | | ``[s]`` ``[/s]`` | ``[s]Outdated information.[/s]`` | .. raw:: html |
  234. | | Strikethrough | | |
  235. | | | <s>Outdated information.</s> |
  236. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  237. | | ``[color]`` ``[/color]`` | ``[color=red]Error![/color]`` | .. raw:: html |
  238. | | Color | | |
  239. | | | <span style="color:red;">Error!</span> |
  240. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  241. | | ``[font]`` ``[/font]`` | ``[font=res://mono.ttf]LICENSE[/font]`` | .. raw:: html |
  242. | | Font | | |
  243. | | | <span style="font-family:monospace;">LICENSE</span> |
  244. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  245. | | ``[img]`` ``[/img]`` | ``[img width=32]res://icon.svg[/img]`` | .. image:: img/icon.svg |
  246. | | Image | | :width: 32 px |
  247. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  248. | | ``[url]`` ``[/url]`` | | ``[url]https://example.com[/url]`` | | https://example.com |
  249. | | Hyperlink | | ``[url=https://example.com]Website[/url]`` | | `Website <https://example.com>`_ |
  250. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  251. | | ``[center]`` ``[/center]`` | ``[center]2 + 2 = 4[/center]`` | .. raw:: html |
  252. | | Horizontal centering | | |
  253. | | | <center>2 + 2 = 4</center> |
  254. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  255. | | ``[kbd]`` ``[/kbd]`` | ``Press [kbd]Ctrl + C[/kbd].`` | Press :kbd:`Ctrl + C`. |
  256. | | Keyboard/mouse shortcut | | |
  257. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  258. | | ``[code]`` ``[/code]`` | ``Returns [code]true[/code].`` | Returns ``true``. |
  259. | | Inline code fragment | | |
  260. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  261. | | ``[codeblock]`` | *See below.* | *See below.* |
  262. | | ``[/codeblock]`` | | |
  263. | | Multiline code block | | |
  264. +--------------------------------+----------------------------------------------+--------------------------------------------------------------+
  265. .. note::
  266. 1. Currently only :ref:`class_@GDScript` has annotations.
  267. 2. ``[kbd]`` disables BBCode until the parser encounters ``[/kbd]``.
  268. 3. ``[code]`` disables BBCode until the parser encounters ``[/code]``.
  269. 4. ``[codeblock]`` disables BBCode until the parser encounters ``[/codeblock]``.
  270. .. warning::
  271. Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``,
  272. always use **four spaces** for indentation (the parser will delete tabs).
  273. ::
  274. ## Do something for this plugin. Before using the method
  275. ## you first have to [method initialize] [MyPlugin].[br]
  276. ## [color=yellow]Warning:[/color] Always [method clean] after use.[br]
  277. ## Usage:
  278. ## [codeblock]
  279. ## func _ready():
  280. ## the_plugin.initialize()
  281. ## the_plugin.do_something()
  282. ## the_plugin.clean()
  283. ## [/codeblock]
  284. func do_something():
  285. pass
  286. By default, ``[codeblock]`` highlights GDScript syntax. You can change it using
  287. the ``lang`` attribute. Currently supported options are:
  288. - ``[codeblock lang=text]`` disables syntax highlighting;
  289. - ``[codeblock lang=gdscript]`` highlights GDScript syntax;
  290. - ``[codeblock lang=csharp]`` highlights C# syntax (only in .NET version).