More doxygenized code

BOINCClientAdapter.h

@@ -17,11 +17,14 @@ using namespace std;
 #define EAH_SHMEM_APP_NAME "EinsteinHS"
 
 /**
+ * \brief Adapter class which facilitates all communications with the BOINC client
+ * 
  * This adapter class can be used to query the BOINC core client as well as the \b Einstein\@Home
  * application for informational data.
  * 
- * \author Oliver Bock
- * \brief Adapter class which facilitates all communications with the BOINC client
+ * \author Oliver Bock\n
+ * Max-Planck-Institute for Gravitational Physics\n
+ * Hannover, Germany
  */
 class BOINCClientAdapter
 {
@@ -33,32 +36,38 @@ public:
 	virtual ~BOINCClientAdapter();
 	
 	/**
-	 * You want to call this method periodically to refresh any volatile client information
 	 * \brief Refreshes dynamic data (e.g. search information)
+	 * 
+	 * You want to call this method periodically to refresh any volatile client information
+	 * 	
 	 * \see AbstractGraphicsEngine::refreshBOINCInformation()
 	 */
 	void refresh();
 	
 	/**
 	 * \brief Retrieves the BOINC core client version of the currently active client
+	 * 
 	 * \return The BOINC core client version
 	 */
 	string coreVersion() const;
 	
 	/**
 	 * \brief Retrieves the \b Einstein\@Home application name of the currently active work unit
+	 * 
 	 * \return The \b Einstein\@Home application name
 	 */
 	string applicationName() const;
 	
 	/**
 	 * \brief Retrieves the \b Einstein\@Home application version of the currently active work unit
+	 * 
 	 * \return The \b Einstein\@Home application version
 	 */
 	string applicationVersion() const;
 	
 	/**
 	 * \brief Retrieves the BOINC user name currently logged in
+	 * 
 	 * \return The BOINC user name
 	 */
 	string userName() const;
@@ -66,36 +75,42 @@ public:
 
 	/**
 	 * \brief Retrieves the BOINC team name of the currently logged in user
+	 * 
 	 * \return The BOINC team name
 	 */
 	string teamName() const;
 	
 	/**
 	 * \brief Retrieves the total project credit of the currently logged in user
+	 * 
 	 * \return The total project credit
 	 */	
 	double userCredit() const;
 	
 	/**
 	 * \brief Retrieves the recent average project credit (RAC) of the currently logged in user
+	 * 
 	 * \return The recent average project credit
 	 */	
 	double userRACredit() const;
 	
 	/**
 	 * \brief Retrieves the total project credit of this host
+	 * 
 	 * \return The total project credit
 	 */	
 	double hostCredit() const;
 	
 	/**
 	 * \brief Retrieves the recent average project credit (RAC) of this host
+	 * 
 	 * \return The recent average project credit
 	 */	
 	double hostRACredit() const;
 
 	/**
 	 * \brief Retrieves the name of the currently active work unit
+	 * 
 	 * \return The work unit name
 	 */
 	string wuName() const;
@@ -107,43 +122,51 @@ public:
 
     /**
 	 * \brief Retrieves the right ascension of the currently searched sky position
+	 * 
 	 * \return The right ascension (in radians)
 	 */
     double wuSkyPosRightAscension() const;
     
     /**
 	 * \brief Retrieves the declination of the currently searched sky position
+	 * 
 	 * \return The right ascension (in radians)
 	 */
     double wuSkyPosDeclination() const;
     
     /**
      * \brief Retrieves the completion fraction of the currently active work unit
+     * 
      * \return The completion fraction (range 0-1)
      */    
     double wuFractionDone() const;
     
     /**
-     * \brief Retrieves the amount of CPU time consumed for the currently active work unit during the active session
+     * \brief Retrieves the amount of CPU time consumed for the currently active work unit
+     * during the active session
+     * 
      * \return The accumulated CPU time consumed during this work unit session (in seconds)
      */
     double wuCPUTime() const;
 	
 private:
     /**
+     * \brief Fetch the contents of \c init_data.xml
+     * 
      * This method uses the BOINC API in order to fill the \c APP_INIT_DATA structure m_UserData
      * with initial information about the current work unit computation session (slot). The data
      * in \c init_data.xml is refreshed only at the beginning of a session, hence this method doesn't
      * need to be called periodically.
-     * \brief Fetch the contents of \c init_data.xml
      */
 	void readUserInfo();
 	
 	/**
+	 * \brief Fetch the contents of the shared memory area provided by the \b Einstein\@Home application
+	 * 
 	 * The shared memory area contains various informational bits and pieces about the running application
 	 * and work unit computation. The contents have to be considered as volatile, hence should be refreshed
 	 * periodically.
-	 * \brief Fetch the contents of the shared memory area provided by the \b Einstein\@Home application
+	 * 	 
 	 * \see refresh()
 	 */
 	void readSharedMemoryArea();
@@ -155,8 +178,9 @@ private:
 	bool m_SharedMemoryAreaAvailable;
 	
 	/**
-	 * Structure returned by the BOINC client API.
-	 * It contains initial information about the current work unit computation session
+	 * \brief Information structure returned by the BOINC client API.
+	 * 
+	 * It contains initial information about the current work unit computation session.
 	 */
 	APP_INIT_DATA m_UserData;
 	

ResourceFactory.h

@@ -7,21 +7,96 @@
 
 #include "Resource.h"
 
+/**
+ * \brief This factory instantiates Resource objects using a given identifier
+ * 
+ * During contruction of the factory object itself it loads all available resources into
+ * an internal cache. The user can subsequently request a copy of this resource by specifying
+ * it using the resource's identifier.
+ *
+ * The resource data is expected to be stored in these three externally linked arrays:
+ * <ul>
+ * 	<li>\ref c_ResourceIdentifiers</li>
+* 	<li>\ref c_ResourceIndex</li> 
+* 	<li>\ref c_ResourceStorage</li>
+ * </ul>
+ * These arrays are compiled using the Open Resource Compiler (ORC) which can be found
+ * in the \c orc subdirectory.
+ * 
+ * \see Resource
+ * \see ResourceCompiler
+ *  
+ * \author Oliver Bock\n
+ * Max-Planck-Institute for Gravitational Physics\n
+ * Hannover, Germany
+ */
 class ResourceFactory
 {
 public:
+	/// Default constructor
 	ResourceFactory();
+	
+	/// Destructor
 	virtual ~ResourceFactory();
 	
+	/**
+	 * \brief Creates an instance of the requested resource
+	 * 
+	 * The identifier has to be the same as the one specified in the \c *.orc file
+	 * used to compile the resources
+	 * 
+	 * \param identifier The identifer of the resource to be instantiated
+	 * 
+	 * \return A constant pointer to the newly instantiated resource
+	 * or NULL if the specified resource could not be found
+	 * 
+	 * \see ResourceCompiler
+	 */
 	const Resource* createInstance(const string identifier);
 	
 private:
+	/// Hashtable mapping identifiers to resource data
 	map<string, vector<unsigned char> > m_ResourceMap;
 };
 
-// TODO: does this need to be global?
+/**
+ * \brief Declaration of the external list of resource identifiers
+ * 
+ * \todo Does this need to be global?
+ * Maybe we should wrap a class around the generated resources?
+ */
 extern const string c_ResourceIdentifiers[];
+
+/**
+ * \brief Declaration of the external list of resource indices
+ * 
+ * This two-dimensional array contains the necessary indices for
+ * every resource in the storage container. Using these indices you
+ * can easily extract a requested resource:
+ * <ol>
+ * 	<li>Offset to the resource</li>
+ * 	<li>Length of the resource</li>
+ * </ol> 
+ * 
+ * \see c_ResourceStorage
+ * 
+ * \todo Does this need to be global?
+ * Maybe we should wrap a class around the generated resources?
+ */
 extern const unsigned int c_ResourceIndex[][2];
+
+/**
+ * \brief Declaration of the external resource storage container
+ * 
+ * The container comprises all resources in a continuous byte sequence
+ * expressed as hex values. Use the resource index to locate/retrieve
+ * a specific resource from the container.
+ * 
+ * \see c_ResourceIndex
+ * 
+ * \todo Does this need to be global?
+ * Maybe we should wrap a class around the generated resources?
+ */
 extern const unsigned char c_ResourceStorage[];
 
 #endif /*RESOURCEFACTORY_H_*/