Implement simple CMake script comment markup language.

The language is very simple. It use ##<keyword> special comment
which opens a structured documentation block and ##end closes it.
This may be used to extract documentation for macro as 'command'
and 'variables' such that cpack --help-command and --help-variable
does parse builtin modules files (CPack.cmake, CPackComponent.cmake,
...) in order to extract the corresponding doc.

1 files changed, 23 insertions, 0 deletions

diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h
index a7a7a1f..2f6e09e 100644
--- a/Source/cmDocumentation.h
+++ b/Source/cmDocumentation.h
@@ -21,6 +21,7 @@
 #include "cmDocumentationFormatterText.h"
 #include "cmDocumentationFormatterUsage.h"
 #include "cmDocumentationSection.h"
+#include "cmake.h"
 
 namespace cmsys
 {
@@ -131,6 +132,28 @@ public:
   /** Add the CPack standard documentation section(s) */
   void addCPackStandardDocSections();
 
+  /**
+   * Get the documentation of macros and variable documented
+   * with CMake structured documentation in a CMake script.
+   * Structured documentation begin with
+   * ## (double sharp) in column 1 & 2 immediately followed
+   * by a markup. Those ## are ignored by the legacy module
+   * documentation parser @see CreateSingleModule.
+   * Current markup are ##macro, ##param, ##variable and ##end
+   * which is closing either of the previous ones.
+   * @param[in] fname the script file name to be parsed for documentation
+   * @param[in,out] commands the vector of command/macros documentation
+   *                entry found in the script file.
+   * @param[in,out] the cmake object instance to which variable documentation
+   *                will be attached (using @see cmake::DefineProperty)
+   * @return the number of documented items (command and variable)
+   *         found in the file.
+   */
+  int getStructuredDocFromFile(const char* fname,
+                               std::vector<cmDocumentationEntry>& commands,
+                               cmake* cm,
+                               const char *docSection);
+  ;
 private:
   void SetForm(Form f);
   void SetDocName(const char* docname);