Add documentation

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: