Merge topic 'some-documentation-fixes'

ceff6ec ccmake: Factor toggle key help instructions.
19da106 ccmake: Document '/' key.
fd63219 ccmake: Align 'g' and 'q' key instructions.
bfb0ed4 Usage: Add missing exepath argument in get_prerequisites documentation.
de51264 Usage: Print help, version and copyright options in usage information.
9ae0604 Usage: Document all options printing the version number.
3353d84 Usage: Document all options printing usage information.
1b612ca Usage: Document -j|--parallel option in help message.
6be15ed Doxygen: Remove dependency on VTK when building doxygen.
a92f14f Doxygen: Fix warnings.
faede37 Doxygen: Generate call graph and relationships.
dd13ecd Doxygen: Improve code documentation.
d0b3a7f Fix typo.
d3d7e45 Remove trailing white-spaces.

Modules/GetPrerequisites.cmake

@@ -24,7 +24,7 @@
 # PARENT_SCOPE.
 #
 #  GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
-#                    <dirs>)
+#                    <exepath> <dirs>)
 # Get the list of shared library files required by <target>. The list in
 # the variable named <prerequisites_var> should be empty on first entry to
 # this function. On exit, <prerequisites_var> will contain the list of

Source/CPack/cmCPackNSISGenerator.h

@@ -72,7 +72,7 @@ protected:
   CreateComponentGroupDescription(cmCPackComponentGroup *group,
                                   cmOStringStream& macrosOut);
 
-  /// Translations any newlines found in the string into \r\n, so that the 
+  /// Translations any newlines found in the string into \\r\\n, so that the
   /// resulting string can be used within NSIS.
   static std::string TranslateNewlines(std::string str);
 };

Source/CPack/cpack.cxx

@@ -448,7 +448,7 @@ int main (int argc, char *argv[])
     doc.SetSection("Name",cmDocumentationName);
     doc.SetSection("Usage",cmDocumentationUsage);
     doc.SetSection("Description",cmDocumentationDescription);
-    doc.SetSection("Options",cmDocumentationOptions);
+    doc.PrependSection("Options",cmDocumentationOptions);
 
     std::vector<cmDocumentationEntry> v;
     cmCPackGeneratorFactory::DescriptionsMap::const_iterator generatorIt;

Source/CTest/cmCTestLaunch.h

@@ -24,7 +24,7 @@ class cmCTestLaunch
 {
 public:
   /** Entry point from ctest executable main().  */
-  static int Main(int argc, const char* const* argv);
+  static int Main(int argc, const char* const argv[]);
 private:
   // Initialize the launcher from its command line.
   cmCTestLaunch(int argc, const char* const* argv);

Source/CTest/cmCTestSubmitHandler.h

@@ -75,7 +75,9 @@ private:
                        const cmStdString& remoteprefix,
                        const cmStdString& url);
 
-  void ParseResponse(std::vector<char>);
+  typedef std::vector<char> cmCTestSubmitHandlerVectorOfChar;
+
+  void ParseResponse(cmCTestSubmitHandlerVectorOfChar chunk);
 
   std::string GetSubmitResultsPrefix();
 

Source/CursesDialog/ccmake.cxx

@@ -116,7 +116,7 @@ int main(int argc, char** argv)
     doc.SetSection("Usage",cmDocumentationUsage);
     doc.SetSection("Description",cmDocumentationDescription);
     doc.SetSection("Generators",generators);
-    doc.SetSection("Options",cmDocumentationOptions);
+    doc.PrependSection("Options",cmDocumentationOptions);
     doc.SetSection("Command",commands);
     doc.SetSection("Compatibility Commands",compatCommands);
     doc.SetSeeAlsoList(cmDocumentationSeeAlso);

Source/CursesDialog/cmCursesMainForm.cxx

@@ -427,17 +427,16 @@ void cmCursesMainForm::PrintKeys(int process /* = 0 */)
       {
       sprintf(firstLine,  "Press [c] to configure                                   ");
       }
-    if (this->AdvancedMode)
     {
-      sprintf(thirdLine,  "Press [t] to toggle advanced mode (Currently On)");
+      const char* toggleKeyInstruction =
+        "Press [t] to toggle advanced mode (Currently %s)";
+      sprintf(thirdLine,
+              toggleKeyInstruction,
+              this->AdvancedMode ? "On" : "Off");
     }
-    else
-      {
-      sprintf(thirdLine,  "Press [t] to toggle advanced mode (Currently Off)");
-      }
-    
     sprintf(secondLine,
-            "Press [h] for help         Press [q] to quit without generating");
+            "Press [h] for help           "
+            "Press [q] to quit without generating");
     }
 
   curses_move(y-4,0);
@@ -1301,6 +1300,5 @@ const char* cmCursesMainForm::s_ConstHelpMessage =
 " g : generate build files and exit, only available when there are no "
 "new options and no errors have been detected during last configuration.\n"
 " l : shows last errors\n"
-" t : toggles advanced mode. In normal mode, only the most important options are shown. In advanced mode, all options are shown. We recommend using normal mode unless you are an expert.\n";
+" t : toggles advanced mode. In normal mode, only the most important options are shown. In advanced mode, all options are shown. We recommend using normal mode unless you are an expert.\n"
-
+" / : search for a variable name.\n";
-

Source/cmCommandArgumentLexer.cxx

@@ -1672,9 +1672,9 @@ YY_BUFFER_STATE cmCommandArgument_yy_scan_string (yyconst char * yystr , yyscan_
 }
 
 /** Setup the input buffer state to scan the given bytes. The next call to cmCommandArgument_yylex() will
- * scan from a @e copy of @a bytes.
+ * scan from a @e copy of @a yybytes.
- * @param bytes the byte buffer to scan
+ * @param yybytes the byte buffer to scan
- * @param len the number of bytes in the buffer pointed to by @a bytes.
+ * @param _yybytes_len the number of bytes in the buffer pointed to by @a bytes.
  * @param yyscanner The scanner object.
  * @return the newly allocated buffer state object.
  */
@@ -1835,7 +1835,7 @@ void cmCommandArgument_yyset_lineno (int  line_number , yyscan_t yyscanner)
 }
 
 /** Set the current column.
- * @param line_number
+ * @param column_no
  * @param yyscanner The scanner object.
  */
 void cmCommandArgument_yyset_column (int  column_no , yyscan_t yyscanner)

Source/cmDependsFortranLexer.cxx

@@ -1991,9 +1991,9 @@ YY_BUFFER_STATE cmDependsFortran_yy_scan_string (yyconst char * yystr , yyscan_t
 }
 
 /** Setup the input buffer state to scan the given bytes. The next call to cmDependsFortran_yylex() will
- * scan from a @e copy of @a bytes.
+ * scan from a @e copy of @a yybytes.
- * @param bytes the byte buffer to scan
+ * @param yybytes the byte buffer to scan
- * @param len the number of bytes in the buffer pointed to by @a bytes.
+ * @param _yybytes_len the number of bytes in the buffer pointed to by @a bytes.
  * @param yyscanner The scanner object.
  * @return the newly allocated buffer state object.
  */
@@ -2154,7 +2154,7 @@ void cmDependsFortran_yyset_lineno (int  line_number , yyscan_t yyscanner)
 }
 
 /** Set the current column.
- * @param line_number
+ * @param column_no
  * @param yyscanner The scanner object.
  */
 void cmDependsFortran_yyset_column (int  column_no , yyscan_t yyscanner)

Source/cmDependsJavaLexer.cxx

@@ -2168,8 +2168,8 @@ YY_BUFFER_STATE cmDependsJava_yy_scan_buffer  (char * base, yy_size_t  size , yy
 }
 
 /** Setup the input buffer state to scan a string. The next call to cmDependsJava_yylex() will
- * scan from a @e copy of @a str.
+ * scan from a @e copy of @a yy_str.
- * @param str a NUL-terminated string to scan
+ * @param yy_str a NUL-terminated string to scan
  * @param yyscanner The scanner object.
  * @return the newly allocated buffer state object.
  * @note If you want to scan bytes that may contain NUL values, then use
@@ -2345,7 +2345,7 @@ void cmDependsJava_yyset_lineno (int  line_number , yyscan_t yyscanner)
 }
 
 /** Set the current column.
- * @param line_number
+ * @param column_no
  * @param yyscanner The scanner object.
  */
 void cmDependsJava_yyset_column (int  column_no , yyscan_t yyscanner)

Source/cmDocumentation.cxx

@@ -21,7 +21,7 @@ static const char *cmDocumentationStandardOptions[][3] =
 {
   {"--copyright [file]", "Print the CMake copyright and exit.",
    "If a file is specified, the copyright is written into it."},
-  {"--help", "Print usage information and exit.",
+  {"--help,-help,-usage,-h,-H,/?", "Print usage information and exit.",
    "Usage describes the basic command line interface and its options."},
   {"--help-full [file]", "Print full help and exit.",
    "Full help displays most of the documentation provided by the UNIX "
@@ -34,7 +34,8 @@ static const char *cmDocumentationStandardOptions[][3] =
   {"--help-man [file]", "Print full help as a UNIX man page and exit.",
    "This option is used by the cmake build to generate the UNIX man page.  "
    "If a file is specified, the help is written into it."},
-  {"--version [file]", "Show program name/version banner and exit.",
+  {"--version,-version,/V [file]",
+   "Show program name/version banner and exit.",
    "If a file is specified, the version is written into it."},
   {0,0,0}
 };

Source/cmDocumentationFormatter.h

@@ -60,7 +60,7 @@ public:
                           std::vector<const cmDocumentationSection *>&)
     {}
 
-  /** Compute a prefix for links into a section (#<prefix>_SOMETHING).  */
+  /** Compute a prefix for links into a section (#\<prefix\>_SOMETHING). */
   std::string ComputeSectionLinkPrefix(std::string const& name);
 };
 

Source/cmExprLexer.cxx

@@ -1554,8 +1554,7 @@ YY_BUFFER_STATE cmExpr_yy_scan_buffer  (char * base, yy_size_t  size , yyscan_t
 }
 
 /** Setup the input buffer state to scan a string. The next call to cmExpr_yylex() will
- * scan from a @e copy of @a str.
+ * scan from a @e copy of @a yy_str.
- * @param str a NUL-terminated string to scan
  * @param yy_str a NUL-terminated string to scan
  * @param yyscanner The scanner object.
  * @return the newly allocated buffer state object.
@@ -1732,7 +1731,7 @@ void cmExpr_yyset_lineno (int  line_number , yyscan_t yyscanner)
 }
 
 /** Set the current column.
- * @param line_number
+ * @param column_no
  * @param yyscanner The scanner object.
  */
 void cmExpr_yyset_column (int  column_no , yyscan_t yyscanner)

Source/cmGlobalGenerator.h

@@ -90,7 +90,7 @@ public:
                                             cmMakefile* mf);
 
   /**
-   * Try running cmake and building a file. This is used for dynalically
+   * Try running cmake and building a file. This is used for dynamically
    * loaded commands, not as part of the usual build process.
    */
   virtual int TryCompile(const char *srcdir, const char *bindir,

Source/cmGlobalKdevelopGenerator.h

@@ -23,8 +23,8 @@ class cmLocalGenerator;
  * cmGlobalKdevelopGenerator produces a project file for KDevelop 3 (KDevelop
  * > 3.1.1).  The project is based on the "Custom Makefile based C/C++"
  * project of KDevelop.  Such a project consists of Unix Makefiles in the
- * build directory together with a <your_project>.kdevelop project file,
+ * build directory together with a \<your_project\>.kdevelop project file,
- * which contains the project settings and a <your_project>.kdevelop.filelist
+ * which contains the project settings and a \<your_project\>.kdevelop.filelist
  * file, which lists the source files relative to the kdevelop project
  * directory. The kdevelop project directory is the base source directory.
  */

Source/cmGlobalUnixMakefileGenerator3.h

@@ -36,7 +36,7 @@ class cmLocalUnixMakefileGenerator3;
  targets that are required to make the process work.
 
  Makefile2 in turn will recursively make targets in the correct order. Each
- target has its own directory <target>.dir and its own makefile build.make in
+ target has its own directory \<target\>.dir and its own makefile build.make in
  that directory. Also in that directory is a couple makefiles per source file
  used by the target. Typically these are named source.obj.build.make and
  source.obj.build.depend.make. The source.obj.build.make contains the rules
@@ -90,7 +90,7 @@ public:
   void WriteHelpRule(std::ostream& ruleFileStream,
                      cmLocalUnixMakefileGenerator3 *);
 
-  // write the top lvel target rules
+  // write the top level target rules
   void WriteConvenienceRules(std::ostream& ruleFileStream,
                              std::set<cmStdString> &emitted);
 

Source/cmGlobalVisualStudio7Generator.h

@@ -48,7 +48,7 @@ public:
                               cmMakefile *, bool optional);
 
   /**
-   * Try running cmake and building a file. This is used for dynalically
+   * Try running cmake and building a file. This is used for dynamically
    * loaded commands, not as part of the usual build process.
    */
   virtual std::string GenerateBuildCommand(const char* makeProgram,

Source/cmLocalGenerator.h

@@ -25,7 +25,7 @@ class cmCustomCommand;
  * \brief Create required build files for a directory.
  *
  * Subclasses of this abstract class generate makefiles, DSP, etc for various
- * platforms. This class should never be constructued directly. A
+ * platforms. This class should never be constructed directly. A
  * GlobalGenerator will create it and invoke the appropriate commands on it.
  */
 class cmLocalGenerator
@@ -90,7 +90,7 @@ public:
   void SetGlobalGenerator(cmGlobalGenerator *gg);
 
   /**
-   * Convert something to something else. This is a centralized coversion
+   * Convert something to something else. This is a centralized conversion
    * routine used by the generators to handle relative paths and the like.
    * The flags determine what is actually done.
    *
@@ -143,6 +143,7 @@ public:
   void AddSharedFlags(std::string& flags, const char* lang, bool shared);
   void AddConfigVariableFlags(std::string& flags, const char* var,
                               const char* config);
+  ///! Append flags to a string.
   virtual void AppendFlags(std::string& flags, const char* newFlags);
   ///! Get the include flags for the current makefile and language
   const char* GetIncludeFlags(const char* lang,

Source/cmLocalUnixMakefileGenerator3.h

@@ -161,7 +161,7 @@ public:
   // used in writing out Cmake files such as WriteDirectoryInformation
   static void WriteCMakeArgument(std::ostream& os, const char* s);
 
-  /** creates the common disclainer text at the top of each makefile */
+  /** creates the common disclaimer text at the top of each makefile */
   void WriteDisclaimer(std::ostream& os);
 
   // write a  comment line #====... in the stream

Source/cmMakefile.h

@@ -668,7 +668,7 @@ public:
    * Expand all defined variables in the string.
    * Defined variables come from the this->Definitions map.
    * They are expanded with ${var} where var is the
-   * entry in the this->Definitions map.  Also @var@ is
+   * entry in the this->Definitions map.  Also \@var\@ is
    * expanded to match autoconf style expansions.
    */
   const char *ExpandVariablesInString(std::string& source);
@@ -682,7 +682,7 @@ public:
 
   /**
    * Remove any remaining variables in the string. Anything with ${var} or
-   * @var@ will be removed.  
+   * \@var\@ will be removed.
    */
   void RemoveVariablesInString(std::string& source,
                                bool atOnly = false) const;

Source/cmake.cxx

@@ -2881,7 +2881,7 @@ int cmake::CheckBuildSystem()
     return 1;
     }
 
-  // Find find the newest dependency.
+  // Find the newest dependency.
   std::vector<std::string>::iterator dep = depends.begin();
   std::string dep_newest = *dep++;
   for(;dep != depends.end(); ++dep)
@@ -2907,7 +2907,7 @@ int cmake::CheckBuildSystem()
       }
     }
 
-  // Find find the oldest output.
+  // Find the oldest output.
   std::vector<std::string>::iterator out = outputs.begin();
   std::string out_oldest = *out++;
   for(;out != outputs.end(); ++out)

Source/ctest.cxx

@@ -68,6 +68,10 @@ static const char * cmDocumentationOptions[][3] =
   {"-F", "Enable failover.", "This option allows ctest to resume a test "
    "set execution that was previously interrupted.  If no interruption "
    "occurred, the -F option will have no effect."},
+  {"-j <jobs>, --parallel <jobs>", "Run the tests in parallel using the"
+   "given number of jobs.",
+   "This option tells ctest to run the tests in parallel using given "
+   "number of jobs."},
   {"-Q,--quiet", "Make ctest quiet.",
     "This option will suppress all the output. The output log file will "
     "still be generated if the --output-log is specified. Options such "
@@ -301,7 +305,7 @@ int main (int argc, char *argv[])
       doc.SetSection("Name",cmDocumentationName);
       doc.SetSection("Usage",cmDocumentationUsage);
       doc.SetSection("Description",cmDocumentationDescription);
-      doc.SetSection("Options",cmDocumentationOptions);
+      doc.PrependSection("Options",cmDocumentationOptions);
       doc.SetSection("Commands",commands);
       doc.SetSeeAlsoList(cmDocumentationSeeAlso);
 #ifdef cout

Utilities/Doxygen/CMakeLists.txt

@@ -17,8 +17,6 @@ INCLUDE (${CMAKE_ROOT}/Modules/Documentation.cmake OPTIONAL)
 
 IF (BUILD_DOCUMENTATION)
 
-  INCLUDE (${CMAKE_ROOT}/Modules/FindVTK.cmake)
-
   #
   # Configure the script and the doxyfile, then add target
   #

Utilities/Doxygen/doxyfile.in

@@ -28,6 +28,8 @@ INCLUDED_BY_GRAPH    = YES
 CLASS_DIAGRAMS       = YES
 GENERATE_LEGEND      = YES
 GRAPHICAL_HIERARCHY  = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
 
 ALLEXTERNALS         = NO
 
@@ -61,7 +63,7 @@ SORT_MEMBER_DOCS     = NO
 DISTRIBUTE_GROUP_DOC = YES
 TAB_SIZE             = 3
 
-FILE_PATTERNS        = *.h *.hxx
+FILE_PATTERNS        = *.h *.hxx *.cxx
 RECURSIVE            = NO
 EXCLUDE_PATTERNS     =