added docu by Claude for PNeXus.

src/external/nexus/PNeXus.cpp

@@ -80,6 +80,20 @@
 
 #include "PNeXus.h"
 
+//=============================================================================
+// nxs::checkHDFType - Determine HDF file format from magic bytes
+//=============================================================================
+/**
+ * @brief Determine the HDF format type of a file by reading its header
+ *
+ * Opens the file in binary mode and reads the first 8 bytes to compare
+ * against known HDF4 and HDF5 magic byte signatures. This allows automatic
+ * format detection before attempting to open the file with the appropriate
+ * library.
+ *
+ * @param filename Path to the file to check
+ * @return nxs::HDFType indicating the format (HDF4, HDF5, or Unknown)
+ */
 nxs::HDFType nxs::checkHDFType(const std::string& filename) {
 
   std::ifstream file(filename, std::ios::binary);
@@ -1996,8 +2010,21 @@ void nxH4::PNeXus::WriteDatasetAttributes(int32 sds_id, const PNXdata<T>& data)
 }
 
 //=============================================================================
-// Group attribute methods
+// Group attribute methods - manage attributes associated with HDF4 groups
 //=============================================================================
+
+/**
+ * @brief Add or update an attribute for a group
+ *
+ * Stores an attribute value in the internal group attributes map. These
+ * attributes will be written when WriteNexusFile() is called. The root
+ * group "/" can be used for file-level attributes.
+ *
+ * @param groupPath HDF4 path of the group (e.g., "/raw_data_1")
+ * @param attrName Attribute name
+ * @param attrValue Attribute value (stored as std::any)
+ * @return true if attribute was added successfully
+ */
 bool nxH4::PNeXus::AddGroupAttribute(const std::string& groupPath,
                            const std::string& attrName,
                            const std::any& attrValue)
@@ -2282,6 +2309,17 @@ int32 nxH4::PNeXus::findDatasetRefByPath(const std::string& path)
   return result_ref;
 }
 
+/**
+ * @brief Convert HDF4 numeric type constant to H4DataType enum
+ *
+ * Maps HDF4 DFNT_* type constants to the library's H4DataType enum for
+ * type-safe handling of dataset types.
+ *
+ * @param hdf4_type HDF4 numeric type constant (e.g., DFNT_INT32)
+ * @return Corresponding H4DataType enum value
+ *
+ * @note Unknown types default to H4DataType::INT32
+ */
 nxH4::H4DataType nxH4::PNeXus::convertHdf4Type(int32 hdf4_type)
 {
   switch (hdf4_type) {
@@ -2298,6 +2336,17 @@ nxH4::H4DataType nxH4::PNeXus::convertHdf4Type(int32 hdf4_type)
   }
 }
 
+/**
+ * @brief Convert H4DataType enum to HDF4 numeric type constant
+ *
+ * Maps the library's H4DataType enum to HDF4 DFNT_* type constants
+ * for writing datasets to HDF4 files.
+ *
+ * @param dataType H4DataType enum value
+ * @return Corresponding HDF4 numeric type constant (e.g., DFNT_INT32)
+ *
+ * @note Unknown types default to DFNT_INT32
+ */
 int32 nxH4::PNeXus::convertToHdf4Type(H4DataType dataType)
 {
   switch (dataType) {
@@ -2426,9 +2475,26 @@ nxH5::PNeXusDeadTime::PNeXusDeadTime(const PNeXus *nxs, bool debug) : fDebug(deb
 // nxH5::PNeXusDeadTime::operator()
 //=============================================================================
 /**
- * @brief Calculates the negative log-likelihood with dead time correction parameter dtc.
- * @param par
- * @return
+ * @brief Calculate the negative log-likelihood for dead time correction
+ *
+ * This function implements the objective function for ROOT Minuit2 minimization.
+ * It calculates the negative log-likelihood comparing observed counts to
+ * the expected count rate model with dead time correction.
+ *
+ * **Model:**
+ * The expected count rate includes:
+ * - Exponential muon decay: N(t) = N0 * exp(-t/tau_mu) + N_bkg
+ * - Dead time correction: N_corrected = N(t) / (1 + N(t) * dtc)
+ *
+ * **Parameters:**
+ * - par[0] (dtc): Dead time correction parameter
+ * - par[1] (N0): Initial count rate amplitude
+ * - par[2] (N_bkg): Background count rate
+ *
+ * @param par Vector of parameters [dtc, N0, N_bkg]
+ * @return Negative log-likelihood value to be minimized
+ *
+ * @note Uses the muon lifetime tau_mu = 2.1969811 microseconds
  */
 double nxH5::PNeXusDeadTime::operator()(const std::vector<double> &par) const
 {
@@ -2452,7 +2518,23 @@ double nxH5::PNeXusDeadTime::operator()(const std::vector<double> &par) const
 // nxH5::PNeXusDeadTime::minimize()
 //=============================================================================
 /**
- * @brief PNeXusDeadTime::minimize
+ * @brief Minimize dead time for a specific detector spectrum
+ *
+ * Performs ROOT Minuit2 minimization to find the optimal dead time parameter
+ * and count rate model parameters for the specified spectrum index. Uses
+ * MnMinimize with strategy 2 (high precision) and stores the result.
+ *
+ * **Minimization Parameters:**
+ * - dtc: Dead time correction (initial: 0.01, step: 0.01)
+ * - N0: Initial count rate (initial: estimated from data)
+ * - N_bkg: Background rate (initial: 0.1)
+ *
+ * @param i Spectrum index to minimize (0-based, must be < dims[1])
+ *
+ * @note Results are stored in fDeadTimeEstimated[i] and optionally printed
+ *       to stdout if debug mode is enabled
+ *
+ * @see GetDeadTimeEstimated() to retrieve results after minimization
  */
 void nxH5::PNeXusDeadTime::minimize(const int i)
 {