AliceO2Group · aphecetche · Mar 17, 2022 · Nov 22, 2019 · Mar 26, 2021 · Oct 26, 2020
@@ -33,7 +33,10 @@ struct ROBoard {
   std::array<uint16_t, 4> patternsNBP{}; /// Non-bending plane pattern
 };
 
-std::ostream& operator<<(std::ostream& os, const ROBoard& loc);
+/// Stream operator for ROBoard
+/// \param os Output stream
+/// \param board Readout board
+std::ostream& operator<<(std::ostream& os, const ROBoard& board);
 
 namespace raw
 {
@@ -57,16 +60,29 @@ static constexpr uint8_t sRESET = 1 << 1;
 static constexpr uint8_t sORB = 1;
 
 /// Tests the local card bit
+/// \param statusWord Status word
+/// \return false if this is a regional board
 inline bool isLoc(uint8_t statusWord) { return (statusWord >> 6) & 0x1; }
+
 /// Tests the calibration bit of the card
+/// \param triggerWord Trigger word
+/// \return true if calibration trigger is fired
 inline bool isCalibration(uint8_t triggerWord) { return ((triggerWord & 0xc) == 0x8); }
-/// Tests if this is a Front End Test event
-inline bool isFET(uint8_t triggerWord) { return ((triggerWord & 0xc) == 0xc); }
+
 /// Gets the crate ID from the absolute local board ID
+/// \param uniqueLocId Unique board ID
+/// \return Crate ID
 inline uint8_t getCrateId(uint8_t uniqueLocId) { return (uniqueLocId >> 4) & 0xF; }
+
 /// Gets the loc ID in the crate from the unique local board ID
+/// \param uniqueLocId Unique board ID
+/// \return Local board ID in crate
 inline uint8_t getLocId(uint8_t uniqueLocId) { return uniqueLocId & 0xF; }
+
 /// Builds the unique loc ID from the crate ID and the loc ID in the crate
+/// \param crateId Crate ID
+/// \param locId Board ID
+/// \return Unique board ID
 inline uint8_t makeUniqueLocID(uint8_t crateId, uint8_t locId) { return locId | (crateId << 4); }
 } // namespace raw
 

@@ -9,7 +9,7 @@
 // granted to it by virtue of its status as an Intergovernmental Organization
 // or submit itself to any jurisdiction.
 
-/// \file   MID/Raw/src/ROBoard.cxx
+/// \file   MID/src/ROBoard.cxx
 /// \brief  Structure to store the readout board information
 /// \author Diego Stocco <Diego.Stocco at cern.ch>
 /// \date   19 November 2019
@@ -23,12 +23,11 @@ namespace o2
 {
 namespace mid
 {
-std::ostream& operator<<(std::ostream& os, const ROBoard& loc)
+std::ostream& operator<<(std::ostream& os, const ROBoard& board)
 {
-  /// Stream operator for ROBoard
-  os << fmt::format("Crate ID: {:2d}  {} ID: {:2d}  status: 0x{:2x}  trig: 0x{:2x}  fired: 0x{:1x}", static_cast<int>(raw::getCrateId(loc.boardId)), (raw::isLoc(loc.statusWord) ? "Loc" : "Reg"), static_cast<int>(raw::getLocId(loc.boardId)), static_cast<int>(loc.statusWord), static_cast<int>(loc.triggerWord), static_cast<int>(loc.firedChambers));
+  os << fmt::format("Crate ID: {:2d}  {} ID: {:2d}  status: 0x{:2x}  trig: 0x{:2x}  fired: 0x{:1x}", static_cast<int>(raw::getCrateId(board.boardId)), (raw::isLoc(board.statusWord) ? "Loc" : "Reg"), static_cast<int>(raw::getLocId(board.boardId)), static_cast<int>(board.statusWord), static_cast<int>(board.triggerWord), static_cast<int>(board.firedChambers));
   for (int ich = 0; ich < 4; ++ich) {
-    os << fmt::format("  X: 0x{:4x} Y: 0x{:4x}", loc.patternsBP[ich], loc.patternsNBP[ich]);
+    os << fmt::format("  X: 0x{:4x} Y: 0x{:4x}", board.patternsBP[ich], board.patternsNBP[ich]);
   }
   return os;
 }

@@ -34,20 +34,29 @@ constexpr int NRPCLines = 9;                  ///< Number of RPC lines
 constexpr int NStripsBP = 16;                 ///< Number of strips in the Bending Plane
 
 /// Gets the chamber index from detection element ID
-/// @param deId The detection element ID
+/// \param deId The detection element ID
 inline int getChamber(int deId) { return (deId % NDetectionElementsPerSide) / NRPCLines; }
 
 /// Gets the chamber index from detection element ID
-/// @param deId The detection element ID
+/// \param deId The detection element ID
 inline int getRPCLine(int deId) { return deId % NRPCLines; }
 
 /// Check if the detection element is in the right side
-/// @param deId The detection element ID
+/// \param deId The detection element ID
 inline bool isRightSide(int deId) { return (deId / NDetectionElementsPerSide) == 0; }
 
+/// Checks if the detection element ID is valid
+/// \param deId The detection element ID
 void assertDEId(int deId);
 
+/// Gets detection element Id
+/// \param isRight RPC is in right side
+/// \param chamber The chamber ID (0-3)
+/// \param rpc RPC ID (0-8)
 int getDEId(bool isRight, int chamber, int rpc);
+
+/// Gets the detection element name from its ID
+/// \param deId The detection element ID
 std::string getDEName(int deId);
 } // namespace detparams
 } // namespace mid

@@ -18,6 +18,7 @@
 #include <stdexcept>
 #include <sstream>
 #include <string>
+#include <fmt/format.h>
 
 namespace o2
 {
@@ -27,26 +28,19 @@ namespace detparams
 {
 void assertDEId(int deId)
 {
-  /// Checks if the detection element ID is valid
-  if (deId < 0 || deId > NDetectionElements) {
-    throw std::out_of_range("Detection element ID must be between 0 and 72");
+  if (deId < 0 || deId >= NDetectionElements) {
+    throw std::out_of_range(fmt::format("Detection element ID must be between 0 and %i", NDetectionElements - 1));
   }
 }
 
 int getDEId(bool isRight, int chamber, int rpc)
 {
-  /// Gets detection element Id
-  /// \param isRight RPC is in right side
-  /// \param chamber The chamber ID (0-3)
-  /// \param rpc RPC ID (0-8)
   int deOffset = (isRight) ? 0 : NDetectionElementsPerSide;
   return deOffset + NRPCLines * chamber + rpc;
 }
 
 std::string getDEName(int deId)
 {
-  /// Gets the detection element name from its ID
-  /// \param deId The detection element ID
   int chId = getChamber(deId);
   int stId = 1 + chId / 2;
   int planeId = 1 + chId % 2;

@@ -55,7 +55,7 @@ class ChannelMasksHandler
 
   /// Applies the mask
   /// \param data Data to be masked. They will be modified
-  /// \return false if data is unmodified
+  /// \return false if the data is completely masked
   bool applyMask(ColumnData& data) const;
 
   /// Merges the masks

@@ -64,8 +64,6 @@ void ChannelMasksHandler::switchOffChannels(const std::vector<ColumnData>& badCh
 
 bool ChannelMasksHandler::applyMask(ColumnData& data) const
 {
-  /// Applies the mask to the data
-  /// Returns false if the data is completely masked
   auto uniqueId = getColumnDataUniqueId(data.deId, data.columnId);
   auto maskIt = mMasks.find(uniqueId);
   if (maskIt == mMasks.end()) {

@@ -24,15 +24,33 @@ namespace o2
 namespace mid
 {
 
+/// Electronics delays
+///
+/// The delays are in local clocks, and correspond to the LHC clocks (aka BCs)
 struct ElectronicsDelay {
-  // The delays are in local clocks, and correspond to the LHC clocks (aka BCs)
-  uint16_t calibToFET{19};
-  uint16_t BCToLocal{93};
-  uint16_t regToLocal{6};
+  uint16_t calibToFET{19}; ///< Delay between calibration and FET
+  uint16_t BCToLocal{93};  ///< Delay between collision BC and local clock
+  uint16_t regToLocal{6};  ///< Delay between regional board and local board answers
 };
 
+/// Output streamer for ElectronicsDelay
+/// \param os Output stream
+/// \param delay Electronics delay structure
 std::ostream& operator<<(std::ostream& os, const ElectronicsDelay& delay);
 
+/// Reads the electronic delays from file
+///
+/// The file must be in the form:
+/// - keyword1 value1
+/// - keyword2 value2
+/// The available keywords are:
+/// - calibToFET
+/// - BCToLocal
+/// - regToLocal
+/// with the same meaning as the corresponding data member of the ElectronicsDelay structure.
+/// If the keyword is not present in the file, the default value is used.
+/// \param filename Path to file with delays
+/// \return ElectronicDelay structure
 ElectronicsDelay readElectronicsDelay(const char* filename);
 
 } // namespace mid

@@ -9,7 +9,7 @@
 // granted to it by virtue of its status as an Intergovernmental Organization
 // or submit itself to any jurisdiction.
 
-/// \file   MIDRaw/ElectronicsDelay.cxx
+/// \file   MID/Raw/src/ElectronicsDelay.cxx
 /// \brief  Delay parameters for MID electronics
 /// \author Diego Stocco <Diego.Stocco at cern.ch>
 /// \date   27 July 2020
@@ -27,7 +27,6 @@ namespace mid
 
 std::ostream& operator<<(std::ostream& os, const ElectronicsDelay& delay)
 {
-  /// Output streamer for ElectronicsDelay
   os << "calibToFET: " << delay.calibToFET << "\n";
   os << "BCToLocal: " << delay.BCToLocal << "\n";
   os << "regToLocal: " << delay.regToLocal << "\n";
@@ -36,7 +35,6 @@ std::ostream& operator<<(std::ostream& os, const ElectronicsDelay& delay)
 
 ElectronicsDelay readElectronicsDelay(const char* filename)
 {
-  /// Reads the electronic delays from file
   ElectronicsDelay electronicsDelay;
   std::ifstream inFile(filename);
   if (inFile.is_open()) {

@@ -9,7 +9,7 @@
 // granted to it by virtue of its status as an Intergovernmental Organization
 // or submit itself to any jurisdiction.
 
-/// \file   mid-digits-to-raw.cxx
+/// \file   MID/Workflow/src/digits-to-raw-workflow.cxx
 /// \brief  MID raw to digits workflow
 /// \author Diego Stocco <Diego.Stocco at cern.ch>
 /// \date   02 October 2019