Update class documentation.

All files have been screened to clean up the documentation so that the actual files may serve as template for further instrument implementations.

Update class documentation.
All files have been screened to clean up the documentation so that the actual files may serve as template for further instrument implementations.
Jürgen Knödlseder
1 parent 7d110f80
Showing 5 changed files with 27 additions and 25 deletions
inst/spi/include/GSPIEventBin.hpp
inst/spi/src/GSPIEventBin.cpp
inst/spi/src/GSPIInstDir.cpp
inst/spi/src/GSPIPointing.cpp
inst/spi/src/GSPIResponse.cpp
@@ -39,12 +39,16 @@
  * @class GSPIEventBin
  *
  * @brief SPI event bin class
+ *
+ * This class defines an event bin of the SPI data space. The class holds
+ * pointers to the bin attributes, and allocates memory so that all bin
+ * attributes have an associated memory space. With this technique, the class
+ * can be used to hold information that is external to GSPIEventBin. The
+ * GSPIEventCube class will use this property to directly manipulate the
+ * pointers of the bin.
  ***************************************************************************/
 class GSPIEventBin : public GEventBin {
  
-    // Friend classes
-    //friend class GSPIEventCube;
-
 public:
     // Constructors and destructors
     GSPIEventBin(void);
@@ -73,12 +77,12 @@ protected:
     void free_members(void);
  
     // Protected members
-    bool         m_alloc;       //!< Signals proper memory allocation
-    int          m_index;       //!< Dataspace index
-    double*      m_counts;      //!< Pointer to number of counts
-    GSPIInstDir* m_dir;         //!< Pointer to bin direction
-    GEnergy*     m_energy;      //!< Pointer to bin energy
-    GTime*       m_time;        //!< Pointer to bin time
+    bool         m_alloc;    //!< Signals memory allocation by object
+    int          m_index;    //!< Dataspace index (-1 if not used)
+    double*      m_counts;   //!< Pointer to number of counts
+    GSPIInstDir* m_dir;      //!< Pointer to bin direction
+    GEnergy*     m_energy;   //!< Pointer to bin energy
+    GTime*       m_time;     //!< Pointer to bin time
 };
  
 #endif /* GSPIEVENTBIN_HPP */
@@ -29,7 +29,6 @@
 #include <config.h>
 #endif
 #include <string>
-#include <cmath>
 #include "GSPIEventBin.hpp"
 #include "GTools.hpp"
  
@@ -53,7 +52,7 @@
  ***************************************************************************/
 GSPIEventBin::GSPIEventBin(void) : GEventBin()
 {
-    // Initialise class members for clean destruction
+    // Initialise class members
     init_members();
  
     // Return
@@ -68,7 +67,7 @@ GSPIEventBin::GSPIEventBin(void) : GEventBin()
  ***************************************************************************/
 GSPIEventBin::GSPIEventBin(const GSPIEventBin& bin) : GEventBin(bin)
 {
-    // Initialise class members for clean destruction
+    // Initialise class members
     init_members();
  
     // Copy members
@@ -171,6 +170,9 @@ GSPIEventBin* GSPIEventBin::clone(void) const
  * @brief Return size of event bin
  *
  * @return Size of event bin (sr MeV s)
+ *
+ * @todo We need to thick about the correct unit for the event bin size
+ * for the SPI telescope. Not sure that "sr" applies here ...
  ***************************************************************************/
 double GSPIEventBin::size(void) const
 {
@@ -232,9 +234,9 @@ std::string GSPIEventBin::print(void) const
  * @brief Initialise class members
  *
  * This method allocates memory for all event bin attributes and intialises
- * the attributes to well defined initial values.
- * 
- * The method assumes that on entry no memory is hold by the member pointers.
+ * the attributes to well defined initial values. The m_alloc member signals
+ * that memory has been allocated, so that memory will be freed upon object
+ * destruction.
  ***************************************************************************/
 void GSPIEventBin::init_members(void)
 {
@@ -245,7 +247,7 @@ void GSPIEventBin::init_members(void)
     m_time   = new GTime;
  
     // Initialise members
-    m_alloc   = true;
+    m_alloc   = true; // Signals that memory has been allocated
     m_index   = -1;   // Signals that event bin does not correspond to cube
     *m_counts = 0.0;
     m_dir->clear();
@@ -286,7 +288,7 @@ void GSPIEventBin::copy_members(const GSPIEventBin&amp; bin)
  * bin), or upon destruction of the object.
  *
  * Note that some logic has been implemented that frees only memory that also
- * has indeed been allocated by the class. Thus if the class only serves as
+ * has indeed been allocated by the object. Thus if the object only serves as
  * container to hold memory pointer allocated by someone else (for example
  * the GSPIEventCube class), no memory is freed.
  ***************************************************************************/
@@ -176,7 +176,7 @@ std::string GSPIInstDir::print(void) const
     // Append header
     result.append("=== GSPIInstDir ===");
  
-    // TODO: Append any other relevat information
+    // TODO: Append any other relevant information
  
     // Return result
     return result;
@@ -223,6 +223,8 @@ std::string GSPIPointing::print(void) const
  
     // Append header
     result.append("=== GSPIPointing ===");
+
+    // Append pointing information
     result.append("\n"+parformat("Pointing direction")+this->dir().print());
  
     // Return result
@@ -29,13 +29,7 @@
 #include <config.h>
 #endif
 #include "GTools.hpp"
-#include "GFits.hpp"
-#include "GCaldb.hpp"
 #include "GSPIResponse.hpp"
-#include "GSPIObservation.hpp"
-#include "GSPIEventBin.hpp"
-#include "GSPIInstDir.hpp"
-#include "GSPIException.hpp"
  
 /* __ Method name definitions ____________________________________________ */
  
@@ -236,7 +230,7 @@ double GSPIResponse::npred(const GPhoton&amp;      photon,
  
  
 /***********************************************************************//**
- * @brief Print SPIPTEL response information
+ * @brief Print SPI response information
  *
  * @return String containing SPI response information.
  ***************************************************************************/