Create getDocumentedModulesListInDir which may be used in other context.

This should makes it easier to use the same "documented module"
techniques for CTest, CMake or user module.

Source/CPack/cpack.cxx

@@ -26,7 +26,6 @@
 #include "cmCPackLog.h"
 
 #include <cmsys/CommandLineArguments.hxx>
-#include <cmsys/Glob.hxx>
 #include <cmsys/SystemTools.hxx>
 #include <memory> // auto_ptr
 
@@ -527,68 +526,26 @@ int main (int argc, char *argv[])
 
     std::vector<cmDocumentationEntry> commands;
 
-    typedef std::pair<std::string,std::string> docModuleSectionPair_t;
-    typedef std::list<docModuleSectionPair_t>  docedModulesList_t;
-    docedModulesList_t     docedModList;
-    docModuleSectionPair_t docPair;
-    std::string            docedFile;
+    std::string                              docedFile;
+    std::string                              docPath;
+    cmDocumentation::documentedModulesList_t docedModList;
 
-    cmsys::Glob gl;
-    std::string findExpr;
-    std::vector<std::string> files;
-    std::string line;
     docedFile = globalMF->GetModulesFile("CPack.cmake");
     if (docedFile.length()!=0)
       {
-      findExpr += cmSystemTools::GetFilenamePath(docedFile.c_str());
-      findExpr += "/CPack*.cmake";
-      if (gl.FindFiles(findExpr))
-        {
-        files = gl.GetFiles();
-        for (std::vector<std::string>::iterator itf=files.begin();
-             itf!=files.end();++itf)
-          {
-          std::ifstream fin((*itf).c_str());
-          if (!fin) continue;
-          if (cmSystemTools::GetLineFromStream(fin, line))
-            {
-            if (line.find("##section")!=std::string::npos)
-              {
-              docPair.first = cmSystemTools::GetFilenameName(*itf);
-              // 10 is the size of '##section' + 1
-              docPair.second = line.substr(10,std::string::npos);
-              docedModList.push_back(docPair);
-              }
-            }
-          else
-            {
-            line.clear();
-            }
-          }
-        }
-      else
-        {
-        // build the list of files to be parsed for documentation
-        // extraction
-        docPair.first  = "CPack.cmake";
-        docPair.second = "Variables common to all CPack generators";
-        docedModList.push_back(docPair);
-        docPair.first  = "CPackComponent.cmake";
-        docedModList.push_back(docPair);
-        }
+      docPath = cmSystemTools::GetFilenamePath(docedFile.c_str());
+      doc.getDocumentedModulesListInDir(docPath,"CPack*.cmake",docedModList);
       }
 
     // parse the files for documentation.
-    for (docedModulesList_t::iterator it = docedModList.begin();
-         it!= docedModList.end(); ++it)
+    cmDocumentation::documentedModulesList_t::iterator docedIt;
+    for (docedIt = docedModList.begin();
+         docedIt!= docedModList.end(); ++docedIt)
       {
-      docedFile = globalMF->GetModulesFile((it->first).c_str());
-      if (docedFile.length()!=0)
-        {
-          doc.GetStructuredDocFromFile(docedFile.c_str(),
-                                       commands,&cminst,(it->second).c_str());
-        }
-     }
+          doc.GetStructuredDocFromFile(
+              (docedIt->first).c_str(),
+              commands,&cminst,(docedIt->second).c_str());
+      }
 
     std::map<std::string,cmDocumentationSection *> propDocs;
     cminst.GetPropertiesDocumentation(propDocs);

Source/cmDocumentation.cxx

@@ -14,6 +14,7 @@
 #include "cmSystemTools.h"
 #include "cmVersion.h"
 #include <cmsys/Directory.hxx>
+#include <cmsys/Glob.hxx>
 
 
 //----------------------------------------------------------------------------
@@ -744,6 +745,60 @@ void cmDocumentation::addCPackStandardDocSections()
             "Variables specific to a CPack generator");
 }
 
+//----------------------------------------------------------------------------
+int cmDocumentation::getDocumentedModulesListInDir(
+          std::string path,
+          std::string globExpr,
+          documentedModulesList_t& docedModuleList)
+{
+  cmsys::Glob gl;
+  std::string findExpr;
+  std::vector<std::string> files;
+  std::string line;
+  documentedModuleSectionPair_t docPair;
+  int nbDocumentedModules = 0;
+
+  findExpr = path + "/" + globExpr;
+  if (gl.FindFiles(findExpr))
+    {
+    files = gl.GetFiles();
+    for (std::vector<std::string>::iterator itf=files.begin();
+        itf!=files.end();++itf)
+      {
+      std::ifstream fin((*itf).c_str());
+      // file access trouble ignore it (ignore this kind of error)
+      if (!fin) continue;
+      /* read first line in order to get doc section */
+      if (cmSystemTools::GetLineFromStream(fin, line))
+        {
+        /* Doc section indicates that
+         * this file has structured doc in it.
+         */
+        if (line.find("##section")!=std::string::npos)
+          {
+          // ok found one more documented module
+          ++nbDocumentedModules;
+          docPair.first = *itf;
+          // 10 is the size of '##section' + 1
+          docPair.second = line.substr(10,std::string::npos);
+          docedModuleList.push_back(docPair);
+          }
+        // No else if no section is found (undocumented module)
+        }
+      // No else cannot read first line (ignore this kind of error)
+      line.clear();
+      }
+    }
+  if (nbDocumentedModules>0)
+    {
+    return 0;
+    }
+  else
+    {
+    return 1;
+    }
+}
+
 //----------------------------------------------------------------------------
 static void trim(std::string& s)
 {

Source/cmDocumentation.h

@@ -35,6 +35,21 @@ public:
   cmDocumentation();
   
   ~cmDocumentation();
+
+  /**
+   * An helper type pair for [structured] documented modules.
+   * The comment of those module contains structure markup
+   * which makes it possible to retrieve the documentation
+   * of variables, macros and functions defined in the module.
+   * - first is the filename of the module
+   * - second is the section of the doc the module belongs too
+   */
+  typedef std::pair<std::string,std::string> documentedModuleSectionPair_t;
+  /**
+   * A list of documented module(s).
+   */
+  typedef std::list<documentedModuleSectionPair_t>  documentedModulesList_t;
+
   // High-level interface for standard documents:
   
   /**
@@ -132,6 +147,21 @@ public:
   /** Add the CPack standard documentation section(s) */
   void addCPackStandardDocSections();
 
+  /**
+   * Retrieve the list of documented module located in
+   * path which match the globing expression globExpr.
+   * @param[in] path, directory where to start the search
+   *                  we will recurse into it.
+   * @param[in] globExpr, the globing expression used to
+   *                      match the file in path.
+   * @param[out] the list of obtained pairs (may be empty)
+   * @return 0 on success 1 on error or empty list
+   */
+  int getDocumentedModulesListInDir(
+          std::string path,
+          std::string globExpr,
+          documentedModulesList_t& docModuleList);
+
   /**
    * Get the documentation of macros, functions and variable documented
    * with CMake structured documentation in a CMake script.
@@ -140,7 +170,8 @@ public:
    * ## (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, ##function, ##variable and ##end.
+   * Current markup are ##section, ##module,
+   * ##macro, ##function, ##variable and ##end.
    * ##end 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