Added comments (Doxygen compliant) to the commited files.

create_database/tuple_reader/BDtaunuMcReader.cc

@@ -6,7 +6,6 @@
 #include "BDtaunuHelpers.h"
 #include "BDtaunuDef.h"
 #include "BDtaunuReader.h"
-#include "BDtaunuReaderStatus.h"
 #include "BDtaunuMcReader.h"
 #include "McGraphManager.h"
 #include "McBTypeCatalogue.h"
@@ -15,14 +14,15 @@ using namespace boost;
 
 const int BDtaunuMcReader::max_mc_length = 100;
 
+// The constructor just needs to allocate and initialize the buffer 
+// and the mc graph manager.
 BDtaunuMcReader::BDtaunuMcReader(
   const char *root_fname,
   const char *root_trname) : 
   BDtaunuReader(root_fname, root_trname) {
 
   AllocateBuffer();
   ClearBuffer();
-
   mc_graph_manager = McGraphManager(this);
 
 }
@@ -32,14 +32,17 @@ BDtaunuMcReader::~BDtaunuMcReader() {
 }
 
 
+// Initializes the input buffer.
 void BDtaunuMcReader::AllocateBuffer() {
 
+  // Allocate space to read in arrays from ntuples. 
   mcLund = new int[max_mc_length];
   mothIdx = new int[max_mc_length];
   dauIdx = new int[max_mc_length];
   dauLen = new int[max_mc_length];
   mcenergy = new float[max_mc_length];
 
+  // Specify the variables where each ntuple branch should be read into. 
   tr->SetBranchAddress("mcLen", &mcLen);
   tr->SetBranchAddress("mcLund", mcLund);
   tr->SetBranchAddress("mothIdx", mothIdx);
@@ -49,6 +52,7 @@ void BDtaunuMcReader::AllocateBuffer() {
 
 }
 
+// Zeros out buffer elements
 void BDtaunuMcReader::ClearBuffer() {
   mcLen = -999;
   continuum = false;
@@ -58,6 +62,7 @@ void BDtaunuMcReader::ClearBuffer() {
   b2_tau_mctype = bdtaunu::kUndefinedTauMcType;
 }
 
+// Free the buffer. Used for destructor. 
 void BDtaunuMcReader::DeleteBuffer() {
   delete[] mcLund;
   delete[] mothIdx;
@@ -66,29 +71,39 @@ void BDtaunuMcReader::DeleteBuffer() {
   delete[] mcenergy;
 }
 
-// get the next event
-int BDtaunuMcReader::next_record() {
+// Read in the next event in the ntuple and update the buffer
+// with the new information.
+RootReader::Status BDtaunuMcReader::next_record() {
 
   ClearBuffer();
 
-  // read next event from root ntuple into the buffer
-  int reader_status = BDtaunuReader::next_record();
+  // Read next event into the buffer. Calls BDtaunuReader::next_record()
+  // first to compute reco information. 
+  RootReader::Status reader_status = BDtaunuReader::next_record();
+
+  // Derive additional mc information from the ntuple. 
+  if (reader_status == RootReader::Status::kReadSucceeded) {
+
+    // This check is necessary since BtaTupleMaker does not save 
+    // this kind of event correctly. Our solution is to skip this
+    // kind of event altogether. 
+    if (is_max_mc_exceeded()) {
+      reader_status = RootReader::Status::kMaxMcParticlesExceeded;
+    } else {
 
-  // proceed only when event is not in an error state
-  if (reader_status == bdtaunu::kReadSucceeded) {
-    if (!is_max_mc_exceeded()) {
+      // Outsource graph operations to graph manager
       mc_graph_manager.construct_graph();
       mc_graph_manager.analyze_graph();
-      FillMCInformation();
-    } else {
-      reader_status = bdtaunu::kMaxMcParticlesExceeded;
+
+      // Make derived information ready for access
+      FillMcInfo();
     }
   }
 
   return reader_status;
 }
 
-void BDtaunuMcReader::FillMCInformation() {
+void BDtaunuMcReader::FillMcInfo() {
   if (mc_graph_manager.get_mcY()) 
     continuum = !(mc_graph_manager.get_mcY()->isBBbar);
   if (mc_graph_manager.get_mcB1()) {

create_database/tuple_reader/BDtaunuMcReader.h

@@ -10,9 +10,24 @@
 #include "BDtaunuReader.h"
 #include "McGraphManager.h"
 
-//! Reads Monte Carlo ntuples and computes truth information. 
-/*! In addition to computing detector response data, this class also
- * computes data related to Monte Carlo truth. */
+/** 
+ * @brief 
+ * Much like its parent class BDtaunuReader, this class reads 
+ * BtaTupleMaker Monte Carlo ntuples generated from the 
+ * BToDTauNuSemiLepHadUser package at SLAC.
+ *
+ *
+ * @detail
+ * In addition to the operations that BDtaunuReader performs, this
+ * class also reads and derives Monte Carlo information. The mechanism and
+ * usage is the same as BDtaunuReader.
+ *
+ * Usage Example
+ * -------------
+ *
+ * See BDtaunuReader. 
+ *
+ */
 class BDtaunuMcReader : public BDtaunuReader {
 
   friend class McGraphManager;
@@ -27,15 +42,13 @@ class BDtaunuMcReader : public BDtaunuReader {
     ~BDtaunuMcReader();
 
     //! Read in the next event. 
-    /*! Returns an integer that indexes the event number. Returns -1
-     * when all events have been read. 
-     *
-     * Calling this automatically computes all features associated
-     * with the event. */
-    virtual int next_record();
+    virtual RootReader::Status next_record();
 
     // Data Accessors
+
+    //! Flag whether the MC truth is Continuum. 
     bool is_continuum() const { return continuum; }
+
     int get_b1_mctype() const { return b1_mctype; }
     int get_b2_mctype() const { return b2_mctype; }
     int get_b1_tau_mctype() const { return b1_tau_mctype; }
@@ -68,7 +81,7 @@ class BDtaunuMcReader : public BDtaunuReader {
     bool is_max_mc_exceeded() { return (mcLen > max_mc_length) ? true : false; }
 
     // Mutator helpers
-    void FillMCInformation();
+    void FillMcInfo();
 
     // MC graph helpers
     McGraphManager mc_graph_manager;

create_database/tuple_reader/BDtaunuReader.cc

@@ -12,7 +12,6 @@
 #include "BDtaunuHelpers.h"
 #include "RootReader.h"
 #include "BDtaunuReader.h"
-#include "BDtaunuReaderStatus.h"
 #include "UpsilonCandidate.h"
 #include "RecoGraphManager.h"
 
@@ -29,13 +28,13 @@ const int BDtaunuReader::maximum_h_candidates = 100;
 const int BDtaunuReader::maximum_l_candidates = 100;
 const int BDtaunuReader::maximum_gamma_candidates = 100;
 
+// The constructor just needs to allocate and initialize the buffer 
+// and the reco graph manager.
 BDtaunuReader::BDtaunuReader(
     const char *root_fname, 
     const char *root_trname) : RootReader(root_fname, root_trname) {
-
   AllocateBuffer();
   ClearBuffer();
-
   reco_graph_manager = RecoGraphManager(this);
 }
 
@@ -44,7 +43,7 @@ BDtaunuReader::~BDtaunuReader() {
 }
 
 
-// All constructors call this function to initialize the class members.
+// Initializes the input buffer.
 void BDtaunuReader::AllocateBuffer() {
 
   // Allocate space to read in arrays from ntuples. 
@@ -210,6 +209,7 @@ void BDtaunuReader::AllocateBuffer() {
 
 }
 
+// Zeros out buffer elements
 void BDtaunuReader::ClearBuffer() {
   platform = -999;
   partition = -999;
@@ -227,6 +227,7 @@ void BDtaunuReader::ClearBuffer() {
   upsilon_candidates.clear();
 }
 
+// Free the buffer. Used for destructor. 
 void BDtaunuReader::DeleteBuffer() {
 
   delete[] YBPairMmissPrime2;
@@ -304,23 +305,32 @@ void BDtaunuReader::DeleteBuffer() {
 
 }
 
-// Read in the next event in the ntuple. It computes all relevant
-// information as a side effect. 
-int BDtaunuReader::next_record() {
+// Read in the next event in the ntuple and update the buffer
+// with the new information.
+RootReader::Status BDtaunuReader::next_record() {
 
   ClearBuffer();
 
-  // read next event from root ntuple into the buffer
-  int reader_status = RootReader::next_record();
+  // Read next event into the buffer. Implicitly uses 
+  // TTree::GetEntry() method.
+  RootReader::Status reader_status = RootReader::next_record();
 
-  // proceed only when event is not in an error state
-  if (reader_status == bdtaunu::kReadSucceeded) {
-    if (!is_max_reco_exceeded()) {
+  // Derive additional reco information from the ntuple. 
+  if (reader_status == RootReader::Status::kReadSucceeded) {
+
+    // This check is necessary since BtaTupleMaker does not save 
+    // this kind of event correctly. Our solution is to skip this
+    // kind of event altogether. 
+    if (is_max_reco_exceeded()) {
+      reader_status = RootReader::Status::kMaxRecoCandExceeded;
+    } else {
+
+      // Outsource graph operations to graph manager
       reco_graph_manager.construct_graph();
       reco_graph_manager.analyze_graph();
-      FillUpsilonCandidates();
-    } else {
-      reader_status = bdtaunu::kMaxRecoCandExceeded;
+
+      // Make derived information ready for access
+      FillRecoInfo();
     }
   } 
 
@@ -350,8 +360,9 @@ std::string BDtaunuReader::get_eventId() const {
          + "/" + std::to_string(lowerID);
 }
 
-void BDtaunuReader::FillUpsilonCandidates() {
+void BDtaunuReader::FillRecoInfo() {
 
+  // Derived information about Upsilon candidates. 
   for (int i = 0; i < nY; i++) {
 
     UpsilonCandidate ups;

create_database/tuple_reader/BDtaunuReader.h

@@ -10,28 +10,61 @@
 #include "UpsilonCandidate.h"
 #include "RecoGraphManager.h"
 
+
+/** 
+ * @brief 
+ * This class is responsible for reading in BtaTupleMaker ntuples
+ * generated from the `BToDTauNuSemiLepHadUser` package at SLAC. 
+ *
+ *
+ * @detail
+ * This class manages a buffer. For each event, it reads in all information 
+ * related to reconstruction into this buffer and computes information needed 
+ * for the analysis. 
+ *
+ * Usage Example
+ * -------------
+ *
+ *     // Open the root file and the TTree (defaults to tree "ntp1").
+ *     BDtaunuReader reader("sp1235r1.root");
+ *
+ *     // Loop over each event. 
+ *     while (reader.next_record() != RootReader::Status::kEOF) {
+ *       // Do stuff... 
+ *       // reader.get_nTrk(); etc.
+ *     }
+ *
+ */
 class BDtaunuReader : public RootReader {
 
+  // Manages reco particle graph and all information computed from it. 
   friend class RecoGraphManager;
 
   public: 
 
     // Constructors
+
+    //! No default constructor.
     BDtaunuReader() = delete;
+
+    //! Open root file root_fname and read the TTree root_trname.
     BDtaunuReader(const char *root_fname, const char *root_trname = "ntp1");
+
+    //! No copy constructor.
     BDtaunuReader(const BDtaunuReader&) = delete;
+
+    //! No copy assignment.
     BDtaunuReader &operator=(const BDtaunuReader&) = delete;
     virtual ~BDtaunuReader();
 
     //! Read in the next event. 
-    /*! Returns an integer that indexes the event number. Returns -1
-     * when all events have been read. 
-     *
+    /*! Reader in next event and returns RootReader::Status.
      * Calling this automatically computes all features associated
      * with the event that the analysis is interested in. */
-    virtual int next_record();
+    virtual RootReader::Status next_record();
+
 
-    // Data Accessors
+    // Accessors
 
     //! Babar event Id. 
     std::string get_eventId() const;
@@ -48,7 +81,7 @@ class BDtaunuReader : public RootReader {
     //! Return list of \f$\Upsilon(4S)\f$ candidates in this event.
     const std::vector<UpsilonCandidate> &get_upsilon_candidates() const { return upsilon_candidates; }
 
-    // Printer
+    //! Prints graphviz file of the reco graph to ostream.
     void print_reco_graph(std::ostream &os) const { reco_graph_manager.print(os); }
 
   protected:
@@ -64,7 +97,8 @@ class BDtaunuReader : public RootReader {
     static const int maximum_gamma_candidates;
 
   private: 
-    // read from root tuples
+
+    // Buffer elements 
     int platform, partition, upperID, lowerID;
     int nTrk;
     float R2All;
@@ -99,7 +133,7 @@ class BDtaunuReader : public RootReader {
     int *hd1Lund, *hd2Lund;
     int *ld1Lund, *ld2Lund, *ld3Lund;
 
-    // computed from root tuples
+    // Data derived from information present in the buffer elements
     std::vector<UpsilonCandidate> upsilon_candidates;
 
   private:
@@ -113,9 +147,10 @@ class BDtaunuReader : public RootReader {
     bool is_max_reco_exceeded() const;
 
     // Mutator helpers
-    void FillUpsilonCandidates();
+    void FillRecoInfo();
 
-    // Reco graph helpers
+    // Reco graph manager. 
+    // Responsible for all reco graph related computations.
     RecoGraphManager reco_graph_manager;
 
 };