Adjusted documentation according to review. Switched to std::string for environment query/adjustment in Process.

3 files changed, 48 insertions, 18 deletions

diff --git a/include/xorg/gtest/environment.h b/include/xorg/gtest/environment.h
index ea0acb9..41f44e4 100644
--- a/include/xorg/gtest/environment.h
+++ b/include/xorg/gtest/environment.h
@@ -73,17 +73,24 @@ class Environment : public ::testing::Environment {
   /**
    * Starts the dummy X server.
    *
-   * Reimplemented from ::testing::Environment. Must not be called directly.
+   * Reimplemented from ::testing::Environment. Should only be called by subclasses.
+   * See Google %Test documentation for details.
    *
    * @throws std::runtime_error if a dummy X server cannot be started.
+   *
+   * @post If successful: subsequent connections to the dummy X server succeed.
+   * @post If successful: %Environment variable DISPLAY contains the
+   * display port for connecting to the dummy X server.
    */
   virtual void SetUp();
 
   /**
    * Stops the dummy X server.
    *
-   * Reimplemented from ::testing::Environment. Must not be called directly.
+   * Reimplemented from ::testing::Environment. Should only be called by subclasses.
+   * See Google %Test documentation for details.
    *
+   * @post Dummy X server stopped.
    */
   virtual void TearDown();
 
diff --git a/include/xorg/gtest/process.h b/include/xorg/gtest/process.h
index 3f022ce..ff545e1 100644
--- a/include/xorg/gtest/process.h
+++ b/include/xorg/gtest/process.h
@@ -69,6 +69,8 @@ class Process {
    * @param args Variadic list of arguments passed to the program.
    *
    * @throws std::runtime_error on failure.
+   *
+   * @post If successful: Child process forked and program started.
    */
   void Start(const std::string& program, va_list args);
 
@@ -81,6 +83,8 @@ class Process {
    * @param program The program to start.
    *
    * @throws std::runtime_error on failure.
+   *
+   * @post If successful: Child process forked and program started.
    */
   void Start(const std::string& program, ...);
 
@@ -91,6 +95,8 @@ class Process {
    *
    * @returns true if termination succeeded, false otherwise.
    *
+   * @post Child process terminated.
+   *
    */
   bool Terminate();
 
@@ -100,28 +106,30 @@ class Process {
    * @throws std::runtime_error if child tries to kill itself.
    *
    * @returns true if kill succeeded, false otherwise.
+   *
+   * @post Child process killed.
    */
   bool Kill();
 
   /**
    * Adjusts the environment of the child process.
    *
-   * @param name Name of the environment variable, must not be NULL.
-   * @param value Value of the environment variable, must not be NULL.
-   * @param overwrite Whether to overwrite the value of existing env variables.
+   * @param [in] name Name of the environment variable.
+   * @param [in] value Value of the environment variable.
+   * @param [in] overwrite Whether to overwrite the value of existing env variables.
    *
    * @throws std::runtime_error if adjusting the environment does not succeed.
    */
-  void SetEnv(const char* name, const char* value, bool overwrite);
+  void SetEnv(const std::string& name, const std::string& value, bool overwrite);
 
   /**
    * Queries the environment of the child process.
    *
-   * @param name The name of the environment variable, must not be NULL.
+   * @param [in] name The name of the environment variable.
    *
-   * @returns The value of the environment variable, or NULL.
+   * @returns The value of the environment variable, or an empty string.
    */
-  const char * GetEnv(const char* name);
+  std::string GetEnv(const std::string& name) const;
 
   /**
    * Accesses the pid of the child process.
diff --git a/include/xorg/gtest/test.h b/include/xorg/gtest/test.h
index 932ced9..f657056 100644
--- a/include/xorg/gtest/test.h
+++ b/include/xorg/gtest/test.h
@@ -33,13 +33,14 @@ namespace testing {
 /**
  * @class Test test.h xorg/gtest/test.h
  *
- * Google %Test fixture checking for running XServer.
+ * Google test fixture providing an Xlib connection to an X11 server.
  *
- * Checks whether an X server is running and establishes
- * a connection to the instance by opening up a display. Rely
- * on Google %Test's TEST_F macro to use this fixture for your
- * own tests or sublcass it and override the SetUp and TearDown
+ * Sets up and tears down an XLib connection to an X11 server.
+ * Rely on Google %Test's TEST_F macro to use this fixture for your
+ * own tests or subclass it and override the SetUp and TearDown
  * methods.
+ *
+ * @remark The display port is read from the environment variable DISPLAY.
  */
 class Test : public ::testing::Test {
  public:
@@ -49,8 +50,11 @@ class Test : public ::testing::Test {
   /**
    * Tries to connect to an X server instance.
    *
-   * Fails if no X server is running.
-   * Reimplemented from ::testing::Test, must not be called directly.
+   * Fails if no X server is running. Updates the display object.
+   * Reimplemented from ::testing::Test, should only be called by subclasses.
+   * See Google %Test documentation for details.
+   *
+   * @post Subsequent calls to Display() return a valid pointer or NULL if an error occured.
    *
    * @throws std::runtime_error if no X server is running.
    */
@@ -59,14 +63,25 @@ class Test : public ::testing::Test {
   /**
    * Closes the display.
    *
-   * Reimplemented from ::testing::Test, must not be called directly.
+   * Reimplemented from ::testing::Test, should only be called by subclasses.
+   * See Google %Test documentation for details.
+   *
+   * @post Subsequent calls to Display() return NULL.
    */
   virtual void TearDown();
 
  protected:
-  /** @cond Implementation */
+
+  /**
+   * Accesses the display representing an Xlib connection.
+   *
+   * Accessible by subclasses and test cases relying on this fixture.
+   *
+   * @returns Pointer to a display or NULL.
+   */
   ::Display* Display() const;
 
+  /** @cond Implementation */
   struct Private;
   std::auto_ptr<Private> d_;
   /** @endcond Implementation */