From 17fe85afbad33793171fbd9688095984cf8bab88 Mon Sep 17 00:00:00 2001
From: Alexander Bock <alexander.bock@me.com>
Date: Thu, 11 May 2017 18:01:36 -0400
Subject: [PATCH] Add documentation

---
 include/openspace/util/documented.h | 49 +++++++++++++++++++++++++++--
 src/util/documented.cpp             | 13 +++++---
 2 files changed, 56 insertions(+), 6 deletions(-)

diff --git a/include/openspace/util/documented.h b/include/openspace/util/documented.h
index 7f9b92a28f..0f701e9a45 100644
--- a/include/openspace/util/documented.h
+++ b/include/openspace/util/documented.h
@@ -30,22 +30,67 @@
 
 namespace openspace {
     
+/*
+ * This abstract class is used for instances when another class has the ability to
+ * generate a Handlebar generated documentation file that contains valuable information
+ * for the user. Instances of this are the DocumentationEngine results, the list of 
+ * Property%s generated by the Scene, or the FactoryEngine results. The documentation is
+ * generated through the writeDocumentation method.
+ * 
+ * The concrete subclass needs to overload the generateJson class that will return the
+ * Json that is parsed by Handlebar to generate the webpage.
+ *
+ * A list of Handlebar templates, the variable name for the result of the generateJson
+ * method, and the Javascript file that contains additional logic is passed in the
+ * constructor.
+ */
 class Documented {
 public:
+    /// This struct contains a single Handlebar template, with the name and the filename
     struct HandlebarTemplate {
-        std::string name;
-        std::string filename;
+        std::string name; ///< The name of the Handlebar template defined in \m filename
+        std::string filename; ///< The filename referenced in the \m name
     };
     
+    /**
+     * The constructor that is used to set the member variables later used in the
+     * writeDocumentation method.
+     * \param name The name of the written documentation
+     * \param jsonName The variable name of the value generated by the generateJson
+     * \param handlebarTemplates A list of Handlebar templates that is added to the 
+     * documentation file
+     * \param javascriptFilename The path to a Javascript source file that is added to the
+     * documentation and that can contain additional functionality
+     * \pre name must not be empty
+     * \pre jsonName must not be empty
+     * \pre Each handlebarTemplates' \c name must not be empty and \c filename must exist
+     * \pre javascriptFilename must not be empty must exist
+     */
     Documented(std::string name, std::string jsonName,
         std::vector<HandlebarTemplate> handlebarTemplates,
         std::string javascriptFilename);
 
+    /// Default constructor
     virtual ~Documented() = default;
     
+    /**
+     * Create the documentation into the provided filename. Any existing file will be
+     * silently overwritten. This method will call the generateJson method that can be
+     * used by concrete subclasses to provide the actual data that is provided in the 
+     * documentation.
+     * \param filename The filename in which the documentation is written
+     */
     void writeDocumentation(const std::string& filename);
     
 protected:
+    /**
+     * This abstract method is used by concrete subclasses to provide the actual data that
+     * is used in the documentation written by this Documented method. The JSON string
+     * returned by this function will be stored in the variable with the \c jsonName as
+     * passed in the constructor.
+     * \return A JSON script that is parsed and stored in the variable passed in the
+     * Documented constructor
+     */
     virtual std::string generateJson() const = 0;
     
 private:
diff --git a/src/util/documented.cpp b/src/util/documented.cpp
index 2fd79dcd9c..95aae556f4 100644
--- a/src/util/documented.cpp
+++ b/src/util/documented.cpp
@@ -51,11 +51,16 @@ Documented::Documented(std::string name,
 {
     ghoul_precondition(!_name.empty(), "name must not be empty");
     ghoul_precondition(!_jsonName.empty(), "jsonName must not be empty");
-    ghoul_precondition(
-        !_handlebarTemplates.empty(),
-        "handlebarTemplates must not be empty"
-    );
+    for (const HandlebarTemplate& t : _handlebarTemplates) {
+        ghoul_precondition(!t.name.empty(), "name must not be empty");
+        ghoul_precondition(!t.filename.empty(), "filename must not be empty");
+        ghoul_precondition(FileSys.fileExists(t.filename), "filename must exist");
+    }
     ghoul_precondition(!_javascriptFile.empty(), "javascriptFilename must not be empty");
+    ghoul_precondition(
+        FileSys.fileExists(_javascriptFile),
+        "javascriptFilename must exist"
+    );
 }
     
 void Documented::writeDocumentation(const std::string& filename) {