improve the doxygen docu with the help of Claude AI.

src/include/PFitter.h

@@ -291,73 +291,294 @@ class PFitter
     Bool_t DoFit();
 
   private:
-    Bool_t fIsValid;     ///< flag. true: the fit is valid.
-    Bool_t fIsScanOnly;  ///< flag. true: scan along some parameters (no fitting).
-    Bool_t fConverged;   ///< flag. true: the fit has converged.
-    Bool_t fChisqOnly;   ///< flag. true: calculate chi^2 only (no fitting).
-    Bool_t fYamlOut;     ///< flag. true: generate yaml output file of the fit results (MINUIT2.OUTPUT -> yaml)
-    Bool_t fUseChi2;     ///< flag. true: chi^2 fit. false: log-max-likelihood
-    UInt_t fPrintLevel;  ///< tag, showing the level of messages whished. 0=minimum, 1=standard, 2=maximum
+    // State flags
+    Bool_t fIsValid;     ///< Overall validity flag: true if fitter initialized successfully
+    Bool_t fIsScanOnly;  ///< Scan mode flag: true if only parameter scans requested (no minimization)
+    Bool_t fConverged;   ///< Convergence flag: true if fit converged to a valid minimum
+    Bool_t fChisqOnly;   ///< Evaluation-only flag: true to calculate χ² without fitting
+    Bool_t fYamlOut;     ///< Output flag: true to generate YAML output file (MINUIT2.OUTPUT → yaml)
+    Bool_t fUseChi2;     ///< Fit mode: true = χ² minimization, false = log-max-likelihood
+    UInt_t fPrintLevel;  ///< Verbosity level: 0=quiet, 1=normal, 2=verbose (Minuit output)
 
-    UInt_t fStrategy; ///< fitting strategy (see minuit2 manual).
+    UInt_t fStrategy; ///< Minuit2 strategy: 0=fast/low-accuracy, 1=default, 2=careful/high-accuracy
 
-    PMsrHandler *fRunInfo; ///< pointer to the msr-file handler
-    PRunListCollection *fRunListCollection; ///< pointer to the run list collection
+    // Core data structures
+    PMsrHandler *fRunInfo; ///< Pointer to MSR file handler (parameters, theory, commands)
+    PRunListCollection *fRunListCollection; ///< Pointer to preprocessed run data collection
 
-    PMsrParamList fParams; ///< msr-file parameters
+    PMsrParamList fParams; ///< Copy of parameter list from MSR file
 
-    PMsrLines      fCmdLines; ///< all the Minuit commands from the msr-file
-    PIntPairVector fCmdList;  ///< command list, first=cmd, second=cmd line index
+    PMsrLines      fCmdLines; ///< Raw command lines from MSR COMMANDS block
+    PIntPairVector fCmdList;  ///< Parsed commands: first=command ID, second=line number
 
-    std::unique_ptr<PFitterFcn> fFitterFcn; ///< pointer to the fitter function object
+    std::unique_ptr<PFitterFcn> fFitterFcn; ///< Objective function for Minuit2 minimization
 
-    ROOT::Minuit2::MnUserParameters fMnUserParams; ///< minuit2 input parameter list
-    std::unique_ptr<ROOT::Minuit2::FunctionMinimum> fFcnMin;       ///< function minimum object
+    ROOT::Minuit2::MnUserParameters fMnUserParams; ///< Minuit2 parameter state (values, errors, limits)
+    std::unique_ptr<ROOT::Minuit2::FunctionMinimum> fFcnMin; ///< Minuit2 function minimum result
 
-    // minuit2 scan/contours command relate variables (see MnScan/MnContours in the minuit2 user manual)
-    Bool_t fScanAll;           ///< flag. false: single parameter scan, true: not implemented yet (see MnScan/MnContours in the minuit2 user manual)
-    UInt_t fScanParameter[2];  ///< scan parameter. idx=0: used for scan and contour, idx=1: used for contour (see MnScan/MnContours in the minuit2 user manual)
-    UInt_t fScanNoPoints;      ///< number of points in a scan/contour (see MnScan/MnContours in the minuit2 user manual)
-    Double_t fScanLow;         ///< scan range low. default=0.0 which means 2 std dev. (see MnScan/MnContours in the minuit2 user manual)
-    Double_t fScanHigh;        ///< scan range high. default=0.0 which means 2 std dev. (see MnScan/MnContours in the minuit2 user manual)
-    PDoublePairVector fScanData; ///< keeps the scan/contour data
+    // Scan and contour analysis
+    Bool_t fScanAll;           ///< Multi-parameter scan flag: false=1D scan, true=2D scan (not fully implemented)
+    UInt_t fScanParameter[2];  ///< Parameter indices: [0]=primary scan/contour, [1]=secondary (contours only)
+    UInt_t fScanNoPoints;      ///< Number of scan/contour evaluation points (default=41)
+    Double_t fScanLow;         ///< Scan lower bound: 0.0 = auto (2σ below current value)
+    Double_t fScanHigh;        ///< Scan upper bound: 0.0 = auto (2σ above current value)
+    PDoublePairVector fScanData; ///< Scan results: (parameter_value, χ²) pairs
 
-    PDoublePairVector fOriginalFitRange; ///< keeps the original fit range in case there is a range command in the COMMAND block
+    PDoublePairVector fOriginalFitRange; ///< Original fit ranges per run (saved for FIT_RANGE command)
 
-    PStringVector fElapsedTime;
+    PStringVector fElapsedTime; ///< Timing information for each fit command
 
-    Bool_t fSectorFlag; ///< sector command present flag    
-    std::vector<PSectorChisq> fSector; ///< stores all chisq/maxLH sector information
+    // Sector χ² analysis
+    Bool_t fSectorFlag; ///< SECTOR command present flag
+    std::vector<PSectorChisq> fSector; ///< Sector analysis results (χ² vs. time windows)
 
-    std::vector<bool> fPhase; ///< flag array in which an entry is true if the related parameter value is a phase
+    std::vector<bool> fPhase; ///< Phase parameter flags: true if parameter is a phase angle
 
-    // phase related functions
+    //----------------------------------------------------------------------
+    // Phase parameter identification (private helpers)
+    //----------------------------------------------------------------------
+
+    /**
+     * @brief Identifies which parameters represent phase angles.
+     *
+     * Scans the THEORY block to detect parameters used as phases in
+     * standard functions (TFieldCos, bessel, etc.). Phase parameters
+     * are constrained to [-360°, +360°] during fitting.
+     */
     void GetPhaseParams();
+
+    /**
+     * @brief Extracts parameter numbers from a FUNCTIONS block entry.
+     *
+     * Parses "funX" references in theory lines to find all parameters
+     * used in the function definition.
+     *
+     * @param funStr Function identifier string (e.g., "fun1", "fun23")
+     * @return Vector of parameter numbers (1-indexed) used in the function
+     */
     PIntVector GetParFromFun(const TString funStr);
+
+    /**
+     * @brief Extracts parameter numbers from a map reference.
+     *
+     * Parses "mapX" references to find mapped parameters across all runs.
+     * Maps allow different runs to use different parameters for the same
+     * theoretical component.
+     *
+     * @param mapStr Map identifier string (e.g., "map1", "map5")
+     * @return Vector of parameter numbers (1-indexed) referenced by the map
+     */
     PIntVector GetParFromMap(const TString mapStr);
 
-    // commands
-    Bool_t CheckCommands();
-    Bool_t SetParameters();    
+    //----------------------------------------------------------------------
+    // Command validation and execution (private methods)
+    //----------------------------------------------------------------------
 
+    /**
+     * @brief Validates COMMANDS block syntax and builds execution queue.
+     *
+     * Parses all command lines, checks for syntax errors, extracts parameters,
+     * and populates fCmdList for sequential execution.
+     *
+     * @return true if all commands are valid, false on syntax errors
+     */
+    Bool_t CheckCommands();
+
+    /**
+     * @brief Transfers MSR parameters to Minuit2 parameter state.
+     *
+     * Initializes fMnUserParams with values, errors, and bounds from the
+     * MSR file's PARAMETERS block.
+     *
+     * @return true if parameters set successfully
+     */
+    Bool_t SetParameters();
+
+    /**
+     * @brief Executes CONTOURS command (2D error contours).
+     *
+     * Calculates confidence regions in 2D parameter space by evaluating
+     * χ² on a grid around the minimum.
+     *
+     * @return true if contour calculation succeeded
+     */
     Bool_t ExecuteContours();
+
+    /**
+     * @brief Executes FIT_RANGE command (optimal time-window search).
+     *
+     * Scans fit quality vs. fit start time to find the optimal first-good-bin.
+     * Useful for determining when background subtraction is adequate.
+     *
+     * @param lineNo Command line number in MSR file
+     * @return true if range scan succeeded
+     */
     Bool_t ExecuteFitRange(UInt_t lineNo);
+
+    /**
+     * @brief Executes FIX command (freeze parameters).
+     *
+     * Prevents specified parameters from varying during subsequent minimization.
+     *
+     * @param lineNo Command line number in MSR file
+     * @return true if parameters fixed successfully
+     */
     Bool_t ExecuteFix(UInt_t lineNo);
+
+    /**
+     * @brief Executes HESSE command (calculate error matrix).
+     *
+     * Computes the covariance matrix by evaluating second derivatives at
+     * the current minimum. Provides symmetric (parabolic) parameter errors.
+     *
+     * @return true if Hessian calculation succeeded
+     */
     Bool_t ExecuteHesse();
+
+    /**
+     * @brief Executes MIGRAD command (gradient descent minimization).
+     *
+     * Runs Minuit2's MIGRAD algorithm, the recommended robust minimizer
+     * using first derivatives and approximate Hessian updates.
+     *
+     * @return true if MIGRAD converged to a valid minimum
+     */
     Bool_t ExecuteMigrad();
+
+    /**
+     * @brief Executes MINIMIZE command (automatic algorithm selection).
+     *
+     * Lets Minuit2 choose the best minimization strategy. Usually equivalent
+     * to MIGRAD for well-behaved problems.
+     *
+     * @return true if minimization converged
+     */
     Bool_t ExecuteMinimize();
+
+    /**
+     * @brief Executes MINOS command (asymmetric error analysis).
+     *
+     * Computes accurate asymmetric confidence intervals by scanning χ²
+     * along each parameter axis. Slower but more accurate than HESSE.
+     *
+     * @return true if MINOS analysis completed
+     */
     Bool_t ExecuteMinos();
+
+    /**
+     * @brief Executes PLOT command (visualize scan/contour results).
+     *
+     * Displays scan or contour data from previous SCAN/CONTOURS commands.
+     *
+     * @return true if plot generated successfully
+     */
     Bool_t ExecutePlot();
+
+    /**
+     * @brief Executes PRINT command (set verbosity level).
+     *
+     * Controls Minuit2 output detail: 0=minimal, 1=normal, 2=debug.
+     *
+     * @param lineNo Command line number in MSR file
+     * @return true if print level set successfully
+     */
     Bool_t ExecutePrintLevel(UInt_t lineNo);
+
+    /**
+     * @brief Executes RELEASE command (unfreeze parameters).
+     *
+     * Allows previously fixed parameters to vary in subsequent fits.
+     *
+     * @param lineNo Command line number in MSR file
+     * @return true if parameters released successfully
+     */
     Bool_t ExecuteRelease(UInt_t lineNo);
+
+    /**
+     * @brief Executes RESTORE command (reload saved parameters).
+     *
+     * Restores parameter values from the last SAVE command.
+     *
+     * @return true if parameters restored successfully
+     */
     Bool_t ExecuteRestore();
+
+    /**
+     * @brief Executes SCAN command (1D parameter space scan).
+     *
+     * Evaluates χ² along one or two parameter axes to visualize the
+     * objective function landscape near the minimum.
+     *
+     * @return true if scan completed
+     */
     Bool_t ExecuteScan();
+
+    /**
+     * @brief Executes SAVE command (store current parameters).
+     *
+     * Saves current parameter state for later RESTORE. Updates MSR file
+     * statistics on first save (after final fit).
+     *
+     * @param first True if this is the first SAVE command in the session
+     * @return true if parameters saved successfully
+     */
     Bool_t ExecuteSave(Bool_t first);
+
+    /**
+     * @brief Executes SIMPLEX command (non-gradient minimization).
+     *
+     * Runs the Nelder-Mead simplex algorithm. Robust for rough objective
+     * functions but slow to converge. Often used before MIGRAD for difficult fits.
+     *
+     * @return true if SIMPLEX found a minimum
+     */
     Bool_t ExecuteSimplex();
+
+    /**
+     * @brief Prepares sector χ² analysis data structures.
+     *
+     * Initializes sector time windows and allocates storage for sector results.
+     *
+     * @param param Current parameter values
+     * @param error Current parameter errors
+     */
     void   PrepareSector(PDoubleVector &param, PDoubleVector &error);
+
+    /**
+     * @brief Executes SECTOR command (time-dependent χ² analysis).
+     *
+     * Calculates χ² for progressively wider time windows to identify
+     * optimal fit ranges and systematic time-dependent effects.
+     *
+     * @param fout Output stream for sector analysis results
+     * @return true if sector analysis completed
+     */
     Bool_t ExecuteSector(std::ofstream &fout);
 
+    //----------------------------------------------------------------------
+    // Utility functions (private)
+    //----------------------------------------------------------------------
+
+    /**
+     * @brief Returns current time in milliseconds.
+     *
+     * Used for timing fit commands and generating performance statistics.
+     *
+     * @return Timestamp in milliseconds since epoch
+     */
     Double_t MilliTime();
+
+    /**
+     * @brief Rounds parameters for output with appropriate precision.
+     *
+     * Determines significant figures based on errors and formats parameters
+     * for display in MSR file output.
+     *
+     * @param par Parameter values
+     * @param err Parameter errors
+     * @param ok Output flag: false if rounding failed
+     * @return Rounded parameter values
+     */
     PDoubleVector ParamRound(const PDoubleVector &par, const PDoubleVector &err, Bool_t &ok);
 };