improve the doxygen docu with the help of Claude AI.

src/include/PFindRun.h

@@ -32,25 +32,134 @@
 
 #include "PMusr.h"
 
+//--------------------------------------------------------------------------
+/**
+ * @brief PFindRun - Locates muSR data files using template-based path resolution.
+ *
+ * This class searches for muSR run data files across multiple paths using
+ * configurable templates that encode instrument naming conventions. It supports
+ * various file formats (ROOT, NeXus, PSI-BIN, PSI-MDU, MUD, WKM) and handles
+ * year/run number substitution in file paths.
+ *
+ * The template system uses placeholders:
+ * - %yyyy% : 4-digit year (e.g., 2023)
+ * - %yy%   : 2-digit year (e.g., 23)
+ * - %rr...r% : Run number with varying digits (%rr%, %rrr%, up to %rrrrrrrrr%)
+ *
+ * @par Example Usage:
+ * @code
+ * PStringVector paths = {"/data/gps", "/data/lem"};
+ * PRunNameTemplateList templates;
+ * PRunNameTemplate gpsTemplate;
+ * gpsTemplate.instrument = "GPS";
+ * gpsTemplate.runNameTemplate = "%yyyy%/%rrrrr%.root";
+ * templates.push_back(gpsTemplate);
+ *
+ * PFindRun finder(paths, templates, "GPS", 2023, 2425, "MusrRoot");
+ * if (finder.FoundPathName()) {
+ *   TString fullPath = finder.GetPathName();
+ *   // fullPath = "/data/gps/2023/02425.root"
+ * }
+ * @endcode
+ *
+ * @see PRunNameTemplate
+ * @see PRunNameTemplateList
+ */
 class PFindRun {
   public:
+    //----------------------------------------------------------------------
+    /**
+     * @brief Default constructor - Creates instance without search parameters.
+     *
+     * Initializes the finder with paths and templates but no specific run to search.
+     * Use the full constructor to perform automatic searches.
+     *
+     * @param path Vector of directory paths to search
+     * @param runNameTemplateList List of template patterns for different instruments
+     */
     PFindRun(const PStringVector path, const PRunNameTemplateList runNameTemplateList);
+
+    //----------------------------------------------------------------------
+    /**
+     * @brief Full constructor - Creates instance and prepares for file search.
+     *
+     * Initializes the finder with all parameters needed to locate a specific run file.
+     * Call FoundPathName() after construction to perform the actual search.
+     *
+     * @param path Vector of directory paths to search
+     * @param runNameTemplateList List of template patterns for different instruments
+     * @param instrument Instrument name (must match a template entry, e.g., "GPS", "LEM")
+     * @param year Run year (e.g., 2023)
+     * @param run Run number (e.g., 2425)
+     * @param file_format Optional file format filter: "MusrRoot"/"ROOT", "NeXus",
+     *                    "PSI-BIN", "PSI-MDU", "MUD", "WKM". Empty string matches any format.
+     */
     PFindRun(const PStringVector path, const PRunNameTemplateList runNameTemplateList,
              const TString &instrument, const UInt_t year, const UInt_t run, const TString file_format="");
 
+    //----------------------------------------------------------------------
+    /**
+     * @brief Searches for the run file using configured templates and paths.
+     *
+     * Iterates through all paths containing the instrument name, applies matching
+     * templates, and checks filesystem for file existence. If a file format is
+     * specified, only files with matching extensions are considered.
+     *
+     * @return true if file was found, false otherwise
+     *
+     * @par Search Algorithm:
+     * 1. Filter paths containing instrument name
+     * 2. For each matching path, try all templates for that instrument
+     * 3. Substitute year/run placeholders to create full path
+     * 4. Check if file exists on filesystem
+     * 5. If file_format specified, verify extension matches
+     *
+     * @note After successful search, use GetPathName() to retrieve the full path.
+     */
     Bool_t  FoundPathName();
+
+    //----------------------------------------------------------------------
+    /**
+     * @brief Returns the full path to the found run file.
+     *
+     * @return Full filesystem path including filename and extension, or empty
+     *         string if no file was found (call FoundPathName() first).
+     */
     TString GetPathName() { return fPathName; }
+
+    //----------------------------------------------------------------------
+    /**
+     * @brief Debug utility - Prints current search configuration to stdout.
+     *
+     * Outputs instrument name, year, run number, and all available templates
+     * with their patterns. Useful for troubleshooting path resolution issues.
+     */
     void DumpTemplateList();
 
   private:
-    const PStringVector fPath;
-    const PRunNameTemplateList fRunNameTemplateList;
-    TString fInstrument{""};
-    Int_t fYear{-1};
-    Int_t fRun{-1};
-    TString fFileFormat{""};
-    TString fPathName{""};
+    const PStringVector fPath;                   ///< Search paths for data files
+    const PRunNameTemplateList fRunNameTemplateList; ///< Template patterns per instrument
+    TString fInstrument{""};                     ///< Target instrument name (e.g., "GPS", "LEM")
+    Int_t fYear{-1};                             ///< Run year (-1 if not specified)
+    Int_t fRun{-1};                              ///< Run number (-1 if not specified)
+    TString fFileFormat{""};                     ///< Optional file format filter (empty = any)
+    TString fPathName{""};                       ///< Resolved full path (empty until found)
 
+    //----------------------------------------------------------------------
+    /**
+     * @brief Generates full file path by substituting template placeholders.
+     *
+     * Internal helper that replaces year and run number placeholders in a template
+     * with actual values. Supports variable-length run number formatting (2-9 digits).
+     *
+     * @param path Base directory path
+     * @param runNameTemplate Template string with placeholders (%yyyy%, %yy%, %rr...r%)
+     * @return Full path with placeholders substituted (e.g., "/data/gps/2023/02425.root")
+     *
+     * @par Template Examples:
+     * - "%yyyy%/%rrrrr%.root" with year=2023, run=42 → "2023/00042.root"
+     * - "run_%yy%_%rrr%.nxs" with year=2023, run=425 → "run_23_425.nxs"
+     */
     TString CreatePathName(const TString path, const TString runNameTemplate);
 };