SW-546: Refine the documentation of SubBandBookKeeping

RTCP/Cobalt/OutputProc/src/TBB_Dipole.h

@@ -117,21 +117,33 @@ namespace LOFAR
 
         /**
          * This structure is for book keeping of received sub-band data.
+         * I create a std::map of this with key = sub-band number in @init where
+         * it is read from the parset which sub-bands shall be expected and the
+         * map is filled accordingly.  If the map does not have an entry for
+         * a sub-band, that sub-band is not given in the parset.
+         *
          * When a new sub-band frame is received it is checked if the map
          * @ref subBandBookKeeping contains an entry that has sub-band number
          * as key.  If not, the sub-band data is unexpected and the frame will
          * be discarded.
          *
          * If the map contains an entry for the sub-band and the entry's
-         * @ref subBandBookKeeping.isInitialised value is false, then the entry
-         * will be set-up with proper data and
+         * @ref subBandBookKeeping.isInitialised value is false, then it is
+         * assumed that the just received frame is the very first frame that
+         * was ever sent for this sub-band and the entry will be set-up with
+         * proper data (setting time0 and slice0 for example) and
          * @ref subBandBookKeeping.isInitialised will be set to true.
          *
+         * Obviously the assumption above that the very first received frame for
+         * a sub-band is the frame that contains time0 and slice0 is breaking
+         * the whole concept that I do not care about the order in which frames
+         * for a sub-band will arrive.  But hey, I have to start somewhere.
+         *
          * From then on it is pretty simple.  Every time a new frame comes in
          * the data of the relevant map entry will be updated.  At some point
          * totalSizeInSamples == currentSizeInSamples will be true and the
          * sub-band data set is complete.  isComplete will be set true and any
-         * future frame that contains more data for this dub-band will be
+         * future frame that contains more data for this sub-band will be
          * discarded.
          */
         struct SubBandBookKeeping