title: Documenting CMake scripts
body: <p>I find myself in a situation where I would like to accurately document a host of custom CMake macros and functions and was wondering how to do it.</p>
  
  <p>The first thing that comes to mind is simply using the built-in syntax and only document scripts, like so:</p>
  
  <pre><code># -----------------------------
  # [FUNCTION_NAME | MACRO_NAME]
  # -----------------------------
  # ... description ...
  # -----------------------------
  </code></pre>
  
  <p>This is fine. However, I'd like to employ common doc generators, for instance doxygen, to also generate external documentation that can be read by anyone <em>without</em> looking at the implementation (which is a common scenario).</p>
  
  <p>One way would be to write a simple parser that generates a corresponding C/C++ header with the appropriate signatures and documentation directly from the CMake script, which could the be processed by doxygen or comparable tools. One could also maintain such a header by hand - which is obviously tedious and error prone.</p>
  
  <p>Is there any other way to employ a documentation generator with CMake scripts?</p>