Repository: CMakePP/CMinx (language: python)

Issue:
[Question] "Keyword" vs "Parameter" directives
**Before opening this issue I:**

- [x] Checked the documentation for answers
- [x] Looked for similar issues
- [x] Did a quick internet search

What's the difference between [`keyword` and `param` directives](https://cmakepp.github.io/CMinx/documenting/function.html#recommended-rest-directives)? They seem to render exactly the same way. 


Discussion / hints:
The `keyword` field is intended to be used for documenting parameters that are parsed by `cmake_parse_argument` whereas `param` is for positional arguments. I can make the documentation more clear on that point.

As for them rendering the same way I think (but I'm not sure) that may depend on the Sphinx theme you use. The only thing I can find in the official Sphinx documentation is [this](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists).  The linked documentation says the `var`, `ivar`, and `cvar` fields are rendered the same, but doesn't comment on any other field, which I take to imply Sphinx does treat `keyword` and `param` differently.

Fix patch:
diff --git a/docs/source/documenting/function.rst b/docs/source/documenting/function.rst
index b542cfb4..c9e61832 100644
--- a/docs/source/documenting/function.rst
+++ b/docs/source/documenting/function.rst
@@ -45,21 +45,30 @@ file. A good template is:
    #    This is a note, it will show up using reST's native note section
    #]]
 
-Recommended reST Directives
-===========================
+The following sections describe the aspects of this template in more detail.
 
-reST's default set of directives encompasses many language nuances which are
-not found in the CMake language. Of the default reST directives, the ones that
-map directly to aspects of the CMake language are:
+Basic Function Documentation
+============================
 
-- ``:param <name of parameter>: <description of parameter>``
-- ``:keyword <name of keyword>: <description of keyword>``
-- ``:type <name of parameter>: <type of parameter named "name of parameter">``
+As an example consider the very simple CMake function ``say_hi_to`` defined as:
 
-Respectively these document: positional arguments, keyword arguments (*i.e.*,
-arguments to be parsed by ``cmake_parse_arguments``), and the type of a
-positional argument or keyword. Unlike most languages CMake does not natively
-support returns.
+.. literalinclude:: ../../../tests/test_samples/basic_function.cmake
+   :language: cmake
+   :lines: 12-14
+
+``say_hi_to`` takes one positional argument ``person`` which is the name of the
+person we want to say hi to.  For documenting positional arguments it is
+recommended you use the ``:param:`` field like:
+
+.. literalinclude:: ../../../tests/test_samples/basic_function.cmake
+   :language: cmake
+   :lines: 3-14
+
+Running CMinx on the documented code will generate:
+
+.. literalinclude:: ../../../tests/test_samples/corr_rst/basic_function.rst
+   :language: rst
+   :lines: 9-17
 
 .. note::
 
@@ -70,13 +79,80 @@ support returns.
    any of the aforementioned types (including other lists) and all objects can
    be implicitly converted to stings.
 
-An example using all three of these directives:
+The documentation comment has three parts:
+
+.. literalinclude:: ../../../tests/test_samples/basic_function.cmake
+   :lines: 4
+   :language: none
+
+is the short/brief description; it's used to quickly summarize what the function
+does. The short description is often used when a user is trying to quickly
+ascertain what functionality a CMake module provides.
+
+.. literalinclude:: ../../../tests/test_samples/basic_function.cmake
+   :lines: 6-7
+   :language: none
+
+is the detailed description; it's used to provide more in depth documentation
+beyond the brief description. Finally,
+
+.. literalinclude:: ../../../tests/test_samples/basic_function.cmake
+   :lines: 9-10
+   :language: none
+
+documents the positional arguments to the function including how they are used
+and what their types.
+
+Documenting Keyword Arguments
+=============================
+
+In modern CMake it is common practice for functions that accept many
+arguments, to accept those arguments as keyword arguments instead of
+positional arguments. As an example consider an "advanced" version of
+``say_hi_to`` defined as:
 
 .. literalinclude:: ../../../tests/test_samples/advanced_function.cmake
    :language: cmake
+   :lines: 15-19
+
+Although not strictly necessary, most CMake function implementations handle
+keyword arguments by calling ``cmake_parse_arguments``. The arguments to
+``cmake_parse_arguments`` are the keywords the function recognizes; in this
+example the keyword arguments are ``PERSONS`` and ``CATS`` (see
+`here <https://cmake.org/cmake/help/latest/command/cmake_parse_arguments.html>`__
+for more details about ``cmake_parse_arguments``).
 
-Assuming the above CMake lives in the file ``advanced_function.cmake``, CMinx
-will generate the reST file:
+Documenting keyword arguments is similar to documenting positional parameters
+except that instead of using the ``:param:`` field, one uses ``:keyword:``:
+
+.. literalinclude:: ../../../tests/test_samples/advanced_function.cmake
+   :language: cmake
+   :lines: 1-19
+
+Running CMinx on this code generates:
 
 .. literalinclude:: ../../../tests/test_samples/corr_rst/advanced_function.rst
    :language: rst
+   :lines: 9-22
+
+.. note::
+
+   While it is recommended that you document positional arguments differently
+   than keyword arguments by using ``:param:`` vs. ``:keyword:`` the resulting
+   HTML documentation may end up rendering the two the same.
+
+Recommended reST Directives
+===========================
+
+reST's default set of directives encompasses many language nuances which are
+not found in the CMake language. Of the default reST directives, the ones that
+map directly to aspects of the CMake language are:
+
+- ``:param <name of parameter>: <description of parameter>``
+- ``:keyword <name of keyword>: <description of keyword>``
+- ``:type <name of parameter>: <type of parameter named "name of parameter">``
+
+Respectively these document: positional arguments, keyword arguments (*i.e.*,
+arguments to be parsed by ``cmake_parse_arguments``), and the type of a
+positional argument or keyword. Unlike most languages CMake does not natively
+support returns.


Test patch:
diff --git a/tests/test_samples/basic_function.cmake b/tests/test_samples/basic_function.cmake
index 9ca6e54b..1d099811 100644
--- a/tests/test_samples/basic_function.cmake
+++ b/tests/test_samples/basic_function.cmake
@@ -1,13 +1,13 @@
 include_guard()
 
 #[[[
-This function has very basic documentation.
-
-This function's description stays close to idealized formatting and does not do
-anything fancy.
-
-:param person: The person this function says hi to
-:type person: string
+# This function has very basic documentation.
+#
+# This function's description stays close to idealized formatting and does not
+# do anything fancy.
+#
+# :param person: The person this function says hi to
+# :type person: string
 #]]
 function(say_hi_to person)
     message("Hi ${person}")
diff --git a/tests/test_samples/corr_rst/basic_function.rst b/tests/test_samples/corr_rst/basic_function.rst
index 3fd10744..6b627ec3 100644
--- a/tests/test_samples/corr_rst/basic_function.rst
+++ b/tests/test_samples/corr_rst/basic_function.rst
@@ -10,8 +10,8 @@ test_samples.basic_function
 
    This function has very basic documentation.
    
-   This function's description stays close to idealized formatting and does not do
-   anything fancy.
+   This function's description stays close to idealized formatting and does not
+   do anything fancy.
    
    :param person: The person this function says hi to
    :type person: string