[Question] "Keyword" vs "Parameter" directives

[peanutfun]

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? They seem to render exactly the same way.

[ryanmrichard]

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. 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.

[ryanmrichard]

@peanutfun let me know if #113 addresses this sufficiently. Thanks!!!

[peanutfun]

From https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists:

param, parameter, arg, argument, key, keyword: Description of a parameter.

It appears to me that param and keyword are synonyms for the same thing, at least regarding the Sphinx directives. But that's fine, as we discuss in #112 that keyword could be used for changing the displayed information on the CMinx side of things. So I think your update of the documentation in #113 addresses this well. Thank you!