cmCTest: Update doxygen to be consistent

Source/cmCTest.h

@@ -53,6 +53,13 @@ class cmXMLWriter;
 #endif
 #define cout no_cout_use_cmCTestLog
 
+/** \class cmCTest
+ * \brief Represents a ctest invocation.
+ *
+ * This class represents a ctest invocation. It is the top level class when
+ * running ctest.
+ *
+ */
 class cmCTest
 {
   friend class cmCTestRunTest;
@@ -119,7 +126,7 @@ public:
   typedef std::vector<cmsys::String> VectorOfStrings;
   typedef std::set<std::string> SetOfStrings;
 
-  ///! Process Command line arguments
+  /** Process Command line arguments */
   int Run(std::vector<std::string>&, std::string* output = CM_NULLPTR);
 
   /**
@@ -135,22 +142,24 @@ public:
    *
    * The execution of the steps (or #Part) should look like this:
    *
+   * /code
    * ctest foo;
    * foo.Initialize();
    * // Set some things on foo
    * foo.ProcessSteps();
    * foo.Finalize();
+   * /endcode
    *
    * \sa Initialize(), Finalize(), Part, PartInfo, SetTest()
    */
   int ProcessSteps();
 
-  /*
+  /**
    * A utility function that returns the nightly time
    */
   struct tm* GetNightlyTime(std::string const& str, bool tomorrowtag);
 
-  /*
+  /**
    * Is the tomorrow tag set?
    */
   bool GetTomorrowTag() { return this->TomorrowTag; }
@@ -160,14 +169,14 @@ public:
    */
   int TestDirectory(bool memcheck);
 
-  ///! what is the configuraiton type, e.g. Debug, Release etc.
+  /** what is the configuraiton type, e.g. Debug, Release etc. */
   std::string const& GetConfigType();
   double GetTimeOut() { return this->TimeOut; }
   void SetTimeOut(double t) { this->TimeOut = t; }
 
   double GetGlobalTimeout() { return this->GlobalTimeout; }
 
-  // how many test to run at the same time
+  /** how many test to run at the same time */
   int GetParallelLevel() { return this->ParallelLevel; }
   void SetParallelLevel(int);
 
@@ -205,19 +214,19 @@ public:
   cmCTest();
   ~cmCTest();
 
-  //! Set the notes files to be created.
+  /** Set the notes files to be created. */
   void SetNotesFiles(const char* notes);
 
   void PopulateCustomVector(cmMakefile* mf, const std::string& definition,
                             std::vector<std::string>& vec);
   void PopulateCustomInteger(cmMakefile* mf, const std::string& def, int& val);
 
-  ///! Get the current time as string
+  /** Get the current time as string */
   std::string CurrentTime();
 
-  //! tar/gzip and then base 64 encode a file
+  /** tar/gzip and then base 64 encode a file */
   std::string Base64GzipEncodeFile(std::string const& file);
-  //! base64 encode a file
+  /** base64 encode a file */
   std::string Base64EncodeFile(std::string const& file);
 
   /**
@@ -227,11 +236,13 @@ public:
    */
   double GetRemainingTimeAllowed();
 
-  ///! Open file in the output directory and set the stream
+  /**
+   * Open file in the output directory and set the stream
+   */
   bool OpenOutputFile(const std::string& path, const std::string& name,
                       cmGeneratedFileStream& stream, bool compress = false);
 
-  ///! Should we only show what we would do?
+  /** Should we only show what we would do? */
   bool GetShowOnly();
 
   bool ShouldUseHTTP10() { return this->UseHTTP10; }
@@ -247,11 +258,11 @@ public:
   std::string GetStopTime() { return this->StopTime; }
   void SetStopTime(std::string const& time);
 
-  // Used for parallel ctest job scheduling
+  /** Used for parallel ctest job scheduling */
   std::string GetScheduleType() { return this->ScheduleType; }
   void SetScheduleType(std::string type) { this->ScheduleType = type; }
 
-  ///! The max output width
+  /** The max output width */
   int GetMaxTestNameWidth() const;
   void SetMaxTestNameWidth(int w) { this->MaxTestNameWidth = w; }
 
@@ -279,31 +290,37 @@ public:
                   std::string* stdErr, int* retVal = CM_NULLPTR,
                   const char* dir = CM_NULLPTR, double timeout = 0.0);
 
-  //! Clean/make safe for xml the given value such that it may be used as
+  /**
-  // one of the key fields by CDash when computing the buildid.
+   * Clean/make safe for xml the given value such that it may be used as
+   * one of the key fields by CDash when computing the buildid.
+   */
   static std::string SafeBuildIdField(const std::string& value);
 
-  //! Start CTest XML output file
+  /** Start CTest XML output file */
   void StartXML(cmXMLWriter& xml, bool append);
 
-  //! End CTest XML output file
+  /** End CTest XML output file */
   void EndXML(cmXMLWriter& xml);
 
-  //! Run command specialized for make and configure. Returns process status
+  /**
-  // and retVal is return value or exception.
+   * Run command specialized for make and configure. Returns process status
+   * and retVal is return value or exception.
+   */
   int RunMakeCommand(const char* command, std::string& output, int* retVal,
                      const char* dir, int timeout, std::ostream& ofs);
 
-  /*
+  /** Return the current tag */
-   * return the current tag
-   */
   std::string GetCurrentTag();
 
-  //! Get the path to the build tree
+  /** Get the path to the build tree */
   std::string GetBinaryDir();
 
-  //! Get the short path to the file. This means if the file is in binary or
+  /**
-  // source directory, it will become /.../relative/path/to/file
+   * Get the short path to the file.
+   *
+   * This means if the file is in binary or
+   * source directory, it will become /.../relative/path/to/file
+   */
   std::string GetShortPathToFile(const char* fname);
 
   enum
@@ -313,7 +330,7 @@ public:
     CONTINUOUS
   };
 
-  // provide some more detailed info on the return code for ctest
+  /** provide some more detailed info on the return code for ctest */
   enum
   {
     UPDATE_ERRORS = 0x01,
@@ -325,14 +342,16 @@ public:
     SUBMIT_ERRORS = 0x40
   };
 
-  ///! Are we producing XML
+  /** Are we producing XML */
   bool GetProduceXML();
   void SetProduceXML(bool v);
 
-  //! Run command specialized for tests. Returns process status and retVal is
+  /**
-  // return value or exception. If environment is non-null, it is used to set
+   * Run command specialized for tests. Returns process status and retVal is
-  // environment variables prior to running the test. After running the test,
+   * return value or exception. If environment is non-null, it is used to set
-  // environment variables are restored to their previous values.
+   * environment variables prior to running the test. After running the test,
+   * environment variables are restored to their previous values.
+   */
   int RunTest(std::vector<const char*> args, std::string* output, int* retVal,
               std::ostream* logfile, double testTimeOut,
               std::vector<std::string>* environment);
@@ -343,13 +362,13 @@ public:
    */
   int ExecuteHandler(const char* handler);
 
-  /*
+  /**
    * Get the handler object
    */
   cmCTestGenericHandler* GetHandler(const char* handler);
   cmCTestGenericHandler* GetInitializedHandler(const char* handler);
 
-  /*
+  /**
    * Set the CTest variable from CMake variable
    */
   bool SetCTestConfigurationFromCMakeVariable(cmMakefile* mf,
@@ -357,37 +376,42 @@ public:
                                               const std::string& cmake_var,
                                               bool suppress = false);
 
-  //! Make string safe to be send as an URL
+  /** Make string safe to be send as an URL */
   static std::string MakeURLSafe(const std::string&);
 
   /** Decode a URL to the original string.  */
   static std::string DecodeURL(const std::string&);
 
-  //! Should ctect configuration be updated. When using new style ctest
+  /**
-  // script, this should be true.
+   * Should ctect configuration be updated. When using new style ctest
+   * script, this should be true.
+   */
   void SetSuppressUpdatingCTestConfiguration(bool val)
   {
     this->SuppressUpdatingCTestConfiguration = val;
   }
 
-  //! Add overwrite to ctest configuration.
+  /**
-  // The format is key=value
+   * Add overwrite to ctest configuration.
+   *
+   * The format is key=value
+   */
   void AddCTestConfigurationOverwrite(const std::string& encstr);
 
-  //! Create XML file that contains all the notes specified
+  /** Create XML file that contains all the notes specified */
   int GenerateNotesFile(const VectorOfStrings& files);
 
-  //! Submit extra files to the server
+  /** Submit extra files to the server */
   bool SubmitExtraFiles(const char* files);
   bool SubmitExtraFiles(const VectorOfStrings& files);
 
-  //! Set the output log file name
+  /** Set the output log file name */
   void SetOutputLogFileName(const char* name);
 
-  //! Set the visual studio or Xcode config type
+  /** Set the visual studio or Xcode config type */
   void SetConfigType(const char* ct);
 
-  //! Various log types
+  /** Various log types */
   enum
   {
     DEBUG = 0,
@@ -400,15 +424,15 @@ public:
     OTHER
   };
 
-  //! Add log to the output
+  /** Add log to the output */
   void Log(int logType, const char* file, int line, const char* msg,
            bool suppress = false);
 
-  //! Get the version of dart server
+  /** Get the version of dart server */
   int GetDartVersion() { return this->DartVersion; }
   int GetDropSiteCDash() { return this->DropSiteCDash; }
 
-  //! Add file to be submitted
+  /** Add file to be submitted */
   void AddSubmitFile(Part part, const char* name);
   std::vector<std::string> const& GetSubmitFiles(Part part)
   {
@@ -416,7 +440,9 @@ public:
   }
   void ClearSubmitFiles(Part part) { this->Parts[part].SubmitFiles.clear(); }
 
-  //! Read the custom configuration files and apply them to the current ctest
+  /**
+   * Read the custom configuration files and apply them to the current ctest
+   */
   int ReadCustomConfigurationFileTree(const char* dir, cmMakefile* mf);
 
   std::vector<std::string>& GetInitialCommandLineArguments()
@@ -424,7 +450,7 @@ public:
     return this->InitialCommandLineArguments;
   }
 
-  //! Set the track to submit to
+  /** Set the track to submit to */
   void SetSpecificTrack(const char* track);
   const char* GetSpecificTrack();
 
@@ -452,10 +478,13 @@ public:
   {
     return this->Definitions;
   }
-  // return the number of times a test should be run
+
+  /** Return the number of times a test should be run */
   int GetTestRepeat() { return this->RepeatTests; }
-  // return true if test should run until fail
+
+  /** Return true if test should run until fail */
   bool GetRepeatUntilFail() { return this->RepeatUntilFail; }
+
 private:
   int RepeatTests;
   bool RepeatUntilFail;
@@ -490,7 +519,7 @@ private:
 
   bool ShowOnly;
 
-  //! Map of configuration properties
+  /** Map of configuration properties */
   typedef std::map<std::string, std::string> CTestConfigurationMap;
 
   std::string CTestConfigFile;
@@ -554,41 +583,41 @@ private:
    */
   int Initialize(const char* binary_dir, cmCTestStartCommand* command);
 
-  //! parse the option after -D and convert it into the appropriate steps
+  /** parse the option after -D and convert it into the appropriate steps */
   bool AddTestsForDashboardType(std::string& targ);
 
-  //! read as "emit an error message for an unknown -D value"
+  /** read as "emit an error message for an unknown -D value" */
   void ErrorMessageUnknownDashDValue(std::string& val);
 
-  //! add a variable definition from a command line -D value
+  /** add a variable definition from a command line -D value */
   bool AddVariableDefinition(const std::string& arg);
 
-  //! parse and process most common command line arguments
+  /** parse and process most common command line arguments */
   bool HandleCommandLineArguments(size_t& i, std::vector<std::string>& args,
                                   std::string& errormsg);
 
-  //! hande the -S -SP and -SR arguments
+  /** hande the -S -SP and -SR arguments */
   void HandleScriptArguments(size_t& i, std::vector<std::string>& args,
                              bool& SRArgumentSpecified);
 
-  //! Reread the configuration file
+  /** Reread the configuration file */
   bool UpdateCTestConfiguration();
 
-  //! Create note from files.
+  /** Create note from files. */
   int GenerateCTestNotesOutput(cmXMLWriter& xml, const VectorOfStrings& files);
 
-  //! Check if the argument is the one specified
+  /** Check if the argument is the one specified */
   bool CheckArgument(const std::string& arg, const char* varg1,
                      const char* varg2 = CM_NULLPTR);
 
-  //! Output errors from a test
+  /** Output errors from a test */
   void OutputTestErrors(std::vector<char> const& process_output);
 
-  //! Handle the --test-action command line argument
+  /** Handle the --test-action command line argument */
   bool HandleTestActionArgument(const char* ctestExec, size_t& i,
                                 const std::vector<std::string>& args);
 
-  //! Handle the --test-model command line argument
+  /** Handle the --test-model command line argument */
   bool HandleTestModelArgument(const char* ctestExec, size_t& i,
                                const std::vector<std::string>& args);