[cmake-developers] documenting a CMake 'use' file

[Brad King]

On 12/10/2013 04:57 PM, Matthew Woehlke wrote:
> Thanks. Are there any guidelines on documenting the parameters of CMake 
> functions/macros? I didn't see that in the mentioned document.

No convention has been established so there is none to document yet.
We can see if any dominant form emerges.

> * ``VAR``: Output variable into which the result will be placed.
> * ``SEP``: String used to join adjacent tokens.
> * ``<ARGN>``: Tokens to be joined.

I suggest using a definition list instead.

> Related; is there a way to turn a CMake module file (that is outside of 
> CMake's module directory) into (e.g. HTML) documentation?

No, and I don't want there to be a way to do this with "cmake".
It will limit our ability to refactor the internal document
generation in the future.  If someone wants to take code from
Utilities/Sphinx and distribute a separately maintained project
specifically to support this use case then that is possible.
I just don't want to restrict modifications to documentation
formatting and tools in our own source tree for compatibility
with external documents.  One of the reasons for using Sphinx
is to avoid making CMake a documentation tool.

-Brad