From a92c4ebfe776b099db228cb49f0fa446a4eab1d4 Mon Sep 17 00:00:00 2001
From: Oliver Bock <oliver.bock@aei.mpg.de>
Date: Wed, 9 Apr 2008 18:22:52 +0200
Subject: [PATCH] More doxygenized code
---
BOINCClientAdapter.h | 42 ++++++++++++++++++------
ResourceFactory.h | 77 +++++++++++++++++++++++++++++++++++++++++++-
2 files changed, 109 insertions(+), 10 deletions(-)
diff --git a/BOINCClientAdapter.h b/BOINCClientAdapter.h
index 5334c55..7bd07a8 100644
--- a/BOINCClientAdapter.h
+++ b/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
+ * periodically.
+ *
* \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;
diff --git a/ResourceFactory.h b/ResourceFactory.h
index f8cc4a7..99b6db6 100644
--- a/ResourceFactory.h
+++ b/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_*/
--
GitLab