From 5d6dfe147d5f0fa493ed66290ca3c521dc9d046f Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Mon, 29 Apr 2024 20:05:19 +0200
Subject: [PATCH] Mention documentation comment support in Shading language

This also updates the shaders style guide accordingly.
---
 .../shader_reference/shading_language.rst     | 37 +++++++++++++++++++
 tutorials/shaders/shaders_style_guide.rst     | 20 ++++++++++
 2 files changed, 57 insertions(+)

diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst
index 3982f6149..09d053eaa 100644
--- a/tutorials/shaders/shader_reference/shading_language.rst
+++ b/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
 ~~~~~~~
 
diff --git a/tutorials/shaders/shaders_style_guide.rst b/tutorials/shaders/shaders_style_guide.rst
index 328f10df1..108954d76 100644
--- a/tutorials/shaders/shaders_style_guide.rst
+++ b/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
 ~~~~~~~~~~