Added documentation for Time class

include/openspace/util/time.h

@@ -26,42 +26,141 @@
 #define __TIME_H__
 
 #include <openspace/scripting/scriptengine.h>
-
 #include <string>
 
 namespace openspace {
 
+/**
+ * This singleton class represents the current simulation time in OpenSpace. It
+ * internally stores the time and provides methods to set the time directly
+ * (setTime(double), setTime(std::string)) using a <code>double</code> value using the 
+ * number of seconds passed since the J2000 epoch or a <code>string</code> that denotes
+ * a valid date string in accordance to the Spice library
+ * (http://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/str2et_c.html). The time can
+ * be retrieved as the number of seconds since the J2000 epoch with currentTime() or as a
+ * UTC string following ISO 8601 with the method currentTimeUTC().
+ *
+ * In addition to the time itself, it also stores a delta time value. This value denotes
+ * the number of seconds that pass for each real-time second. This value is set with
+ * setDeltaTime(double), retrieved with deltaTime() and solely used in the
+ * advanceTime(double), which takes a <code>tickTime</code> parameter. The value of the
+ * parameter is dependent on the usage of the class and must be equal to the real-world 
+ * time that has passed since the last call to the method. For example, if the
+ * advanceTime(double) method is called each frame, the <code>tickTime</code> has to be
+ * equal to the frame time.
+ */
 class Time {
 public:
-	static bool initialize();
+	/**
+	 * Initializes the Time singleton and loads an LSK spice kernel with the provided
+	 * name.
+	 * \param lskKernel The name of the kernel that should be loaded during the
+	 * initialization. If the parameter is empty, no kernel will be loaded
+	 * \return <code>true</code> if the initialization succeeded, <code>false</code>
+	 * otherwise
+	 */
+	static bool initialize(const std::string& lskKernel = "");
+
+	/**
+	 * Deinitializes the Time singleton. This method will not unload the kernel that was
+	 * possibly loaded during the initialize method.
+	 */
 	static void deinitialize();
+
+	/**
+	 * Returns the reference to the Time singleton object.
+	 * \return The reference to the Time singleton object
+	 */
     static Time& ref();
+
+	/**
+	 * Returns <code>true</code> if the singleton has been successfully initialized,
+	 * <code>false</code> otherwise
+	 * \return <code>true</code> if the singleton has been successfully initialized,
+	 * <code>false</code> otherwise
+	 */
 	static bool isInitialized();
 	
-	double advanceTime(double tickTime);
-	
+	/**
+	 * Sets the current time to the specified value in seconds past the J2000 epoch. This
+	 * value can be negative to represent dates before the epoch.
+	 * \param The number of seconds after the J2000 epoch
+	 */
 	void setTime(double value);
-	double currentTime() const;
+
+	/**
+	 * Sets the current time to the specified value given as a Spice compliant string as
+	 * described in the Spice documentation
+	 * (http://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/str2et_c.html)
+	 * \param time The time to be set as a date string
+	 */
 	void setTime(std::string time);
+
+	/**
+	 * Returns the current time as the number of seconds past the J2000 epoch. If the
+	 * current time is a date before that epoch, the returned value will be negative.
+	 * \return The current time as the number of seconds past the J2000 epoch
+	 */
+	double currentTime() const;
+
+	/**
+	 * Returns the current time as a formatted date string compliant with ISO 8601 and
+	 * thus also compliant with the Spice library.
+	 * \return The current time as a formatted date string
+	 */
 	std::string currentTimeUTC() const;
 
+	/**
+	 * Sets the delta time value that is the number of seconds that should pass for each
+	 * real-time second. This value is used in the advanceTime(double) method to easily
+	 * advance the simulation time.
+	 * \param deltaT The number of seconds that should pass for each real-time second
+	 */
 	void setDeltaTime(double deltaT);
+
+	/**
+	 * Returns the delta time, that is the number of seconds that pass in the simulation
+	 * for each real-time second
+	 * \return The number of seconds that pass for each real-time second
+	 */
 	double deltaTime() const;
 
+	/**
+	 * Advances the simulation time using the deltaTime() and the <code>tickTime</code>.
+	 * The deltaTime() is the number of simulation seconds that pass for each real-time
+	 * second. <code>tickTime</code> is the number of real-time seconds that passed since
+	 * the last call to this method. If this method is called in the render loop, the
+	 * <code>tickTime</code> should be equivalent to the frame time.
+	 * \param tickTime The number of real-time seconds that passed since the last call
+	 * to this method
+	 * \return The new time value after advancing the time
+	 */
+	double advanceTime(double tickTime);
+
+	/**
+	 * Returns the Lua library that contains all Lua functions available to change the
+	 * current time, retrieve the current time etc. The functions contained are
+	 * - time_setDeltaTime
+	 * - time_deltaTime
+	 * - time_currentTime
+	 * - time_currentTimeUTC
+	 * \return The Lua library that contains all Lua functions available to change the
+	 * Time singleton
+	 */
 	static scripting::ScriptEngine::LuaLibrary luaLibrary();
 
 private:
+	/// Creates the time object. Only used in the initialize() method
 	Time();
 	Time(const Time& src) = delete;
     Time& operator=(const Time& rhs) = delete;
 
-	static Time* _instance;
-	double _time;
+	static Time* _instance; ///< The singleton instance
+	double _time; ///< The time stored as the number of seconds past the J2000 epoch
 
-	double _deltaTimePerSecond;
+	double _deltaTimePerSecond; ///< The delta time that is used to advance the time
 };
 
-
 } // namespace openspace
 
 #endif // __TIME_H__