Merge pull request #9300 from Calinou/shading-language-doc-comments

Mention documentation comment support in Shading language

tutorials/shaders/shader_reference/shading_language.rst

@@ -85,6 +85,43 @@ Most GLSL ES 3.0 datatypes are supported:
 | **samplerCubeArray** | Sampler type for binding Cubemap arrays, which are read as float.               |
 +----------------------+---------------------------------------------------------------------------------+
 
+Comments
+~~~~~~~~
+
+The shading language supports the same comment syntax as used in C# and C++:
+
+.. code-block:: glsl
+
+    // Single-line comment.
+    int a = 2;  // Another single-line comment.
+
+    /*
+    Multi-line comment.
+    The comment ends when the ending delimiter is found
+    (here, it's on the line below).
+    */
+    int b = 3;
+
+Additionally, you can use documentation comments that are displayed in the
+inspector when hovering a shader parameter. Documentation comments are currently
+only supported when placed immediately above a ``uniform`` declaration. These
+documentation comments only support the **multiline** comment syntax and must use
+**two** leading asterisks (``/**``) instead of just one (``/*``):
+
+.. code-block:: glsl
+
+    /**
+     * This is a documentation comment.
+     * These lines will appear in the inspector when hovering the shader parameter
+     * named "Something".
+     * You can use [b]BBCode[/b] [i]formatting[/i] in the comment.
+     */
+    uniform int something = 1;
+
+The asterisks on the follow-up lines are not required, but are recommended as
+per the :ref:`doc_shaders_style_guide`. These asterisks are automatically
+stripped by the inspector, so they won't appear in the tooltip.
+
 Casting
 ~~~~~~~
 

tutorials/shaders/shaders_style_guide.rst

@@ -218,6 +218,26 @@ Don't use multiline comment syntax if your comment can fit on a single line:
    press :kbd:`Ctrl + K`. This feature adds or removes ``//`` at the start of
    the selected lines.
 
+Documentation comments
+~~~~~~~~~~~~~~~~~~~~~~
+
+Use the following format for documentation comments above uniforms, with **two**
+leading asterisks (``/**``) and follow-up asterisks on every line:
+
+.. code-block:: glsl
+
+    /**
+     * This is a documentation comment.
+     * These lines will appear in the inspector when hovering the shader parameter
+     * named "Something".
+     * You can use [b]BBCode[/b] [i]formatting[/i] in the comment.
+     */
+    uniform int something = 1;
+
+These comments will appear when hovering a property in the inspector. If you
+don't wish the comment to be visible in the inspector, use the standard comment
+syntax instead (``// ...`` or ``/* ... */`` with only one leading asterisk).
+
 Whitespace
 ~~~~~~~~~~