From 42e47c8e24d0351e7edb1d7289997d340514cfbc Mon Sep 17 00:00:00 2001 From: Andreas Suter Date: Tue, 25 Nov 2025 08:52:43 +0100 Subject: [PATCH] improve the doxygen docu of PSubTextEdit.* (musredit_qt6). --- src/musredit_qt6/musredit/PSubTextEdit.cpp | 291 ++++++++++++++++++++- src/musredit_qt6/musredit/PSubTextEdit.h | 271 ++++++++++++++++++- 2 files changed, 550 insertions(+), 12 deletions(-) diff --git a/src/musredit_qt6/musredit/PSubTextEdit.cpp b/src/musredit_qt6/musredit/PSubTextEdit.cpp index 2c6e61ae8..ea36a8b31 100644 --- a/src/musredit_qt6/musredit/PSubTextEdit.cpp +++ b/src/musredit_qt6/musredit/PSubTextEdit.cpp @@ -27,6 +27,22 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PSubTextEdit.cpp + * @brief Implementation of the enhanced msr file text editor. + * + * @details Provides the implementation of PSubTextEdit class methods for + * inserting msr file blocks via specialized dialogs. Each method handles + * dialog creation, user interaction, validation, and text insertion at the + * current cursor position. + * + * The implementation emphasizes error handling, input validation, and user + * feedback to minimize msr file syntax errors and improve editing workflow. + * + * @author Andreas Suter + * @date 2009-2025 + */ + #include #include @@ -53,10 +69,33 @@ //---------------------------------------------------------------------------------------------------- /** - *

Constructor. + * @brief Constructor - Initializes the enhanced text editor. * - * \param admin pointer to the musredit internal administration object. - * \param parent pointer to the parent object. + * @details Constructs a PSubTextEdit instance with access to the global + * administration object. The constructor is minimal, delegating most + * initialization to the QPlainTextEdit base class. + * + * The administration object provides: + * - Theory function definitions for block insertion + * - Help URLs for context-sensitive documentation + * - Application configuration and preferences + * + * @param admin Pointer to the PAdmin global administration object. This + * pointer is stored for later use by block insertion methods. + * If nullptr, block insertion features will not work properly + * as they depend on theory function definitions and help URLs. + * @param parent Pointer to the parent widget. Typically nullptr as this + * editor is embedded in a QTabWidget where the tab widget + * manages widget ownership and lifetime. + * + * @note The constructor performs no special initialization beyond storing + * the admin pointer. All QPlainTextEdit functionality is available + * immediately. + * @note Block insertion methods should check fAdmin for nullptr before use, + * though in normal operation it should never be null. + * + * @see PAdmin For the global administration object + * @see QPlainTextEdit For base class functionality */ PSubTextEdit::PSubTextEdit(PAdmin *admin, QWidget *parent) : QPlainTextEdit(parent), @@ -66,8 +105,56 @@ PSubTextEdit::PSubTextEdit(PAdmin *admin, QWidget *parent) : //---------------------------------------------------------------------------------------------------- /** - * @brief PSubTextEdit::getFitType - * @return + * @brief Retrieves the fit type from the current msr file content. + * + * @details Parses the entire text editor content to locate the "fittype" + * keyword and extract its associated integer value. The fittype determines + * the analysis mode and affects which parameters are required in RUN blocks. + * + * **Parsing Algorithm:** + * 1. Convert all editor text to QString + * 2. Search for first occurrence of "fittype" keyword + * 3. Skip whitespace after "fittype" + * 4. Extract first non-whitespace character after "fittype" + * 5. Convert character to integer + * 6. Return value if conversion succeeds + * + * **Fittype Values:** + * - **0**: Single histogram fit - fits a single detector histogram directly + * - **2**: Asymmetry fit - calculates asymmetry from forward/backward histograms + * - **4**: µSR-MnF fit - special mode for muon spin rotation in magnetic fields + * - **8**: Non-µSR fit - general x-y data fitting for arbitrary data + * + * **Return Value Interpretation:** + * - Valid fittype (0, 2, 4, 8): Normal operation, fittype found and parsed + * - **-1**: Error condition - keyword not found or invalid value + * + * **Usage Context:** + * This method is useful for: + * - Validating msr file completeness before saving + * - Determining appropriate RUN block format for insertion + * - Conditional behavior based on analysis mode + * - Error checking during file editing + * + * **Limitations:** + * - Only finds the first occurrence of "fittype" + * - Does not validate that fittype is in a RUN block context + * - Single-digit parsing only (assumes fittype value is 0-9) + * - Case-sensitive search for "fittype" keyword + * + * @return int The fittype value (0, 2, 4, or 8) if found and valid, + * -1 if "fittype" keyword not found, value is not numeric, or + * parsing fails for any reason. + * + * @note This method searches the entire document on each call; it is not + * optimized for frequent queries. + * @note Only the first occurrence of "fittype" is processed; multiple RUN + * blocks with different fittypes will only report the first. + * @note The method assumes fittype appears as "fittype". + * + * @see insertAsymRunBlock() Uses fittype 2 + * @see insertSingleHistRunBlock() Uses fittype 0 + * @see insertNonMusrRunBlock() Uses fittype 8 */ int PSubTextEdit::getFitType() { @@ -91,7 +178,38 @@ int PSubTextEdit::getFitType() //---------------------------------------------------------------------------------------------------- /** - *

Starts the msr-title input dialog window. + * @brief Slot: Inserts a title block via dialog. + * + * @details Launches PGetTitleBlockDialog to gather title input from the user. + * If the dialog is accepted, inserts the entered title at the current cursor + * position with a trailing newline. + * + * **Dialog Workflow:** + * 1. Create PGetTitleBlockDialog with help URL from PAdmin + * 2. Display dialog modally (blocks until user responds) + * 3. If user accepts: retrieve title and insert into text editor + * 4. If user cancels: perform no action + * + * **Insertion Behavior:** + * - Text is inserted at current cursor position + * - Trailing newline separates title from subsequent blocks + * - Existing text is not affected + * - Insertion is undoable via Edit → Undo + * + * **Help Integration:** + * The dialog receives a help URL retrieved from PAdmin using the "title" key. + * This provides context-sensitive documentation about title block format and + * best practices. + * + * @note Uses std::unique_ptr for automatic dialog cleanup. + * @note Null check on dialog pointer is defensive programming; in normal + * operation, make_unique should not return nullptr. + * @note The comment about hard-coded URLs is outdated; URLs are retrieved + * from PAdmin configuration. + * + * @see PGetTitleBlockDialog For the title input dialog implementation + * @see PAdmin::getHelpUrl() For help URL retrieval + * @see insertPlainText() Qt method for text insertion */ void PSubTextEdit::insertTitle() { @@ -126,9 +244,58 @@ void PSubTextEdit::insertParameterBlock() //---------------------------------------------------------------------------------------------------- /** - *

Inserts the selected theory item. + * @brief Slot: Inserts a specific theory function. * - * \param name of the theory item to be added. + * @details Looks up the specified theory function by name in the PAdmin + * theory registry, formats it with placeholder parameters, and inserts it + * at the current cursor position. + * + * **Function Lookup Process:** + * 1. Search PAdmin theory registry for function matching given label + * 2. If not found, silently return (no insertion) + * 3. If found, retrieve PTheory definition + * 4. Format function line with name, parameters, and comment + * + * **Formatted Output:** + * Standard functions: + * @code + * functionName 1 2 3 (comment describing parameters) + * @endcode + * + * User-defined functions (userFcn): + * @code + * userFcn libMyLibrary.so TMyFunction 1 2 (parameters) + * @endcode + * + * **Parameter Placeholders:** + * Numbers (1, 2, 3, ...) are placeholder parameter indices that users must + * replace with actual FITPARAMETER references or map variables before the + * msr file can be used for fitting. + * + * **User Function Special Handling:** + * The "userFcn" theory function requires library and function names, so + * placeholder values "libMyLibrary.so" and "TMyFunction" are inserted + * for the user to replace with actual names. + * + * **Insertion Behavior:** + * - Text inserted at current cursor position + * - Trailing newline for proper block separation + * - Existing text unaffected + * - Operation is undoable + * + * @param name Label of the theory function to insert. Must match a label + * in the PAdmin theory registry (e.g., "simpleGss", "asymmetry", + * "cosPol", "userFcn"). + * + * @note If name not found in registry, method returns silently without + * error message or user feedback. + * @note Parameter numbers start at 1 (not 0) to match musrfit conventions. + * @note The comment from PTheory provides parameter descriptions to guide + * users in understanding what each parameter represents. + * + * @see PAdmin::getTheoryItem() For retrieving theory function definitions + * @see PTheory For theory function structure definition + * @see insertTheoryBlock() For interactive theory block building */ void PSubTextEdit::insertTheoryFunction(QString name) { @@ -478,7 +645,53 @@ void PSubTextEdit::insertNonMusrRunBlock() //---------------------------------------------------------------------------------------------------- /** - *

Insert the command block. + * @brief Slot: Inserts a default COMMANDS block. + * + * @details Inserts a standard COMMANDS block with commonly used MINUIT + * commands for batch fitting. This block controls the MINUIT minimizer + * behavior during the fit process. + * + * **Inserted Commands:** + * + * - **SET BATCH**: Suppresses interactive prompts, allowing unattended execution + * - **STRATEGY 1**: Balance between speed and accuracy (0=fast, 2=thorough) + * - **MINIMIZE**: Executes the minimization algorithm to find best parameters + * - **#MINOS**: (Commented out) Computes asymmetric parameter errors + * - **SAVE**: Saves fitted parameter values back to msr file + * - **END RETURN**: Exits MINUIT and returns to musrfit + * + * **MINUIT Strategy Levels:** + * - Strategy 0: Fast, less accurate gradient/Hessian calculations + * - Strategy 1: Default, good balance (recommended for most fits) + * - Strategy 2: Thorough, most accurate but slowest + * + * **MINOS Command:** + * MINOS is commented out (#MINOS) by default because: + * - It significantly increases fit time + * - It's only needed when asymmetric errors are important + * - Users can uncomment it when needed for publication-quality results + * + * **Customization:** + * Users can edit the inserted block to: + * - Change STRATEGY level based on fit complexity + * - Uncomment MINOS for asymmetric error calculation + * - Add additional MINUIT commands (SIMPLEX, SEEK, IMPROVE, etc.) + * - Modify convergence criteria with SET commands + * + * **Block Structure:** + * The block is delimited by: + * - Header: "###..." separator line + * - Body: "COMMANDS" keyword followed by command lines + * - Footer: "END RETURN" to exit command mode + * - Double newline for separation from next block + * + * @note This is the only insertion method that doesn't use a dialog, + * as COMMANDS blocks have a standard structure. + * @note The block is inserted at current cursor position with proper + * formatting and delimiters. + * @note All insertions are undoable via Edit → Undo. + * + * @see MINUIT documentation for complete command reference */ void PSubTextEdit::insertCommandBlock() { @@ -528,7 +741,65 @@ void PSubTextEdit::insertPlotBlock() //---------------------------------------------------------------------------------------------------- /** - *

Insert a default msr-statistics block. + * @brief Slot: Inserts a default STATISTIC block. + * + * @details Inserts a STATISTIC block template with the current timestamp + * and placeholder values for fit results. After fitting, musrfit updates + * these placeholders with actual fit statistics. + * + * **Inserted Content:** + * + * @code + * ############################################################### + * STATISTIC --- 2025-01-15 14:23:45 + * chisq = ????, NDF = ????, chisq/NDF = ???? + * @endcode + * + * **Block Components:** + * - **Separator line**: Visual delimiter (63 # characters) + * - **STATISTIC keyword**: Identifies the block type + * - **Timestamp**: Current date and time in "yyyy-MM-dd hh:mm:ss" format + * - **Placeholder line**: Template for fit quality metrics + * + * **Placeholder Values:** + * - **chisq**: Chi-square value measuring fit quality (lower is better) + * - **NDF**: Number of degrees of freedom (data points - parameters) + * - **chisq/NDF**: Normalized chi-square (should be ~1 for good fit) + * + * **Fit Quality Interpretation:** + * - chisq/NDF ≈ 1: Good fit, data matches theory within errors + * - chisq/NDF << 1: Overestimated errors or over-fitting + * - chisq/NDF >> 1: Underestimated errors or poor model + * + * **Usage Workflow:** + * 1. User inserts STATISTIC block template (this method) + * 2. User completes msr file with other required blocks + * 3. User runs musrfit on the msr file + * 4. musrfit replaces "????" with actual values + * 5. User reviews fit statistics to assess quality + * + * **Timestamp Purpose:** + * The timestamp records when the fit was performed, useful for: + * - Tracking fit history and iterations + * - Documenting analysis workflow + * - Identifying most recent results + * - Version control and reproducibility + * + * **Multiple STATISTIC Blocks:** + * Users can have multiple STATISTIC blocks to record fit history: + * - Initial fit with default parameters + * - After parameter adjustments + * - After fixing certain parameters + * - Final publication-quality fit + * + * @note The timestamp reflects insertion time, not fit time. musrfit + * updates the timestamp when it updates fit statistics. + * @note Placeholder "????" clearly indicates values not yet computed. + * @note Double newline provides separation from subsequent content. + * @note Insertion is undoable via Edit → Undo. + * + * @see QDateTime::currentDateTime() For timestamp generation + * @see musrfit For the fitting application that updates placeholders */ void PSubTextEdit::insertStatisticBlock() { diff --git a/src/musredit_qt6/musredit/PSubTextEdit.h b/src/musredit_qt6/musredit/PSubTextEdit.h index 452a6154c..b5e935d1b 100644 --- a/src/musredit_qt6/musredit/PSubTextEdit.h +++ b/src/musredit_qt6/musredit/PSubTextEdit.h @@ -27,6 +27,26 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PSubTextEdit.h + * @brief Enhanced text editor widget for editing msr files in musredit. + * + * @details This header defines the PSubTextEdit class which extends + * QPlainTextEdit to provide specialized functionality for editing musrfit + * msr (muon spin rotation/relaxation fit) files. The class provides + * convenient methods for inserting structured blocks that comprise an msr + * file, with dialog-based assistance for each block type. + * + * @author Andreas Suter + * @date 2009-2025 + * @copyright Copyright (C) 2009-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see PAdmin Global administration object + * @see musredit Main editor application + * @see QPlainTextEdit Qt base class for plain text editing + */ + #ifndef _PSUBTEXTEDIT_H_ #define _PSUBTEXTEDIT_H_ @@ -37,33 +57,280 @@ //------------------------------------------------------------------------------------------ /** - *

Class handling a single text edit tab within musredit. + * @class PSubTextEdit + * @brief Enhanced text editor for msr file editing with block insertion support. + * + * @details This class extends QPlainTextEdit to provide specialized editing + * capabilities for musrfit msr files. It offers dialog-based assistants for + * inserting the various structured blocks that comprise an msr file, reducing + * errors and improving workflow efficiency. + * + * @par MSR File Structure: + * An msr file contains several required and optional blocks: + * - **Title**: Optional descriptive title + * - **FITPARAMETER**: Fit parameters with initial values and constraints + * - **THEORY**: Mathematical theory functions describing the expected signal + * - **FUNCTIONS**: User-defined mathematical functions + * - **RUN**: One or more run blocks specifying data files and fit configuration + * - **COMMANDS**: MINUIT minimization commands + * - **FOURIER**: Optional Fourier transform specifications + * - **PLOT**: Plot configuration for data visualization + * - **STATISTIC**: Fit results (chi-square, NDF, etc.) + * + * @par Block Insertion Features: + * Each insertion method launches a specialized dialog that: + * - Guides users through required and optional parameters + * - Validates input to prevent syntax errors + * - Provides context-sensitive help + * - Inserts properly formatted text at cursor position + * + * @par Run Block Types: + * Different fit types require different run block formats: + * - **Asymmetry (fittype 2)**: Standard µSR asymmetry analysis + * - **Single Histogram (fittype 0)**: Direct histogram fitting + * - **Non-µSR (fittype 8)**: General x-y data fitting + * + * @par Theory Function Support: + * The class provides access to all available theory functions from the + * PAdmin configuration, allowing quick insertion of common functions like: + * - Exponential relaxation (simpleExp, simpleGss) + * - Oscillations (cosPol, polyKT) + * - Static Kubo-Toyabe (statKT, dynKT) + * - User-defined functions (userFcn) + * + * @par Validation and Error Handling: + * - Input validation occurs during block creation + * - Invalid or incomplete data triggers warning dialogs + * - Default values are inserted for missing critical parameters + * - Users are informed about required corrections + * + * @par Workflow Integration: + * - Tab-based interface allows multiple files open simultaneously + * - Each tab contains a PSubTextEdit instance + * - Cursor position determines insertion point + * - Undo/redo support through QPlainTextEdit base class + * + * @note This class is used as the editor widget within each tab of musredit. + * @note All block insertion operations are undoable via standard edit commands. + * @note The class relies on PAdmin for theory function definitions and help URLs. + * + * @see PAdmin For theory function definitions and configuration + * @see PGetTitleBlockDialog For title input + * @see PGetParameterBlockDialog For parameter block creation + * @see PGetTheoryBlockDialog For theory block creation + * @see PGetFunctionsBlockDialog For functions block creation + * @see PGetAsymmetryRunBlockDialog For asymmetry run blocks + * @see PGetSingleHistoRunBlockDialog For single histogram run blocks + * @see PGetNonMusrRunBlockDialog For non-µSR run blocks + * @see PGetFourierBlockDialog For Fourier block creation + * @see PGetPlotBlockDialog For plot block creation */ class PSubTextEdit : public QPlainTextEdit { Q_OBJECT public: + /** + * @brief Constructs the enhanced text editor. + * + * @details Initializes the text editor with access to the global + * administration object for theory functions and configuration. + * + * @param admin Pointer to PAdmin object containing theory function + * definitions, help URLs, and application configuration. + * If nullptr, block insertion features may not work properly. + * @param parent Pointer to parent widget. Typically nullptr as this + * widget is embedded in a tab widget. + * + * @see PAdmin For the global administration object + */ PSubTextEdit(PAdmin *admin = 0, QWidget *parent = 0); + + /** + * @brief Virtual destructor. + * + * @details Default destructor. Qt's parent-child ownership handles cleanup. + * + * @note Declared virtual for proper cleanup in inheritance hierarchies. + */ virtual ~PSubTextEdit() {} + + /** + * @brief Retrieves the fit type from the current msr file content. + * + * @details Parses the text editor content to find and extract the fittype + * value. The fittype determines the analysis mode and run block format: + * - 0: Single histogram fit + * - 2: Asymmetry fit + * - 4: µSR-MnF fit + * - 8: Non-µSR fit + * + * @return int The fittype value if found and valid, -1 otherwise. + * + * @note Returns -1 if "fittype" keyword not found or value is invalid. + * @note Only finds the first occurrence of "fittype" in the document. + */ int getFitType(); public slots: + /** + * @brief Slot: Inserts a title block via dialog. + * + * @details Launches PGetTitleBlockDialog for entering or editing the + * optional msr file title. If accepted, inserts the title text at the + * current cursor position. + * + * @see PGetTitleBlockDialog For the title input dialog + */ void insertTitle(); + + /** + * @brief Slot: Inserts a FITPARAMETER block via dialog. + * + * @details Launches PGetParameterBlockDialog for creating the FITPARAMETER + * block with initial values, constraints, and parameter naming. This block + * defines all parameters used in the theory functions. + * + * @see PGetParameterBlockDialog For the parameter block dialog + */ void insertParameterBlock(); + + /** + * @brief Slot: Inserts a specific theory function. + * + * @details Inserts a single theory function line based on the given + * function name. The function is looked up in the PAdmin theory function + * registry and formatted with placeholder parameter numbers. + * + * @param name Label of the theory function to insert (e.g., "simpleGss", + * "asymmetry", "userFcn"). + * + * @note This is typically called from a menu action triggered by the user + * selecting a specific theory function. + * + * @see PAdmin::getTheoryItem() For theory function definitions + */ void insertTheoryFunction(QString name); + + /** + * @brief Slot: Inserts a THEORY block via dialog. + * + * @details Launches PGetTheoryBlockDialog which provides an interactive + * interface for building complex theory blocks by combining multiple + * theory functions with addition and multiplication operators. + * + * @see PGetTheoryBlockDialog For the theory block dialog + */ void insertTheoryBlock(); + + /** + * @brief Slot: Inserts a FUNCTIONS block via dialog. + * + * @details Launches PGetFunctionsBlockDialog for creating user-defined + * mathematical functions that can be used in theory expressions. Functions + * allow complex mathematical expressions to be reused. + * + * @see PGetFunctionsBlockDialog For the functions block dialog + */ void insertFunctionBlock(); + + /** + * @brief Slot: Inserts an asymmetry RUN block via dialog. + * + * @details Launches PGetAsymmetryRunBlockDialog for creating a RUN block + * configured for asymmetry fitting (fittype 2). This is the most common + * µSR analysis mode with forward/backward detector histograms and + * asymmetry calculation. + * + * Validates all required fields and provides default values for missing + * critical parameters with appropriate warnings. + * + * @see PGetAsymmetryRunBlockDialog For the asymmetry run block dialog + */ void insertAsymRunBlock(); + + /** + * @brief Slot: Inserts a single histogram RUN block via dialog. + * + * @details Launches PGetSingleHistoRunBlockDialog for creating a RUN block + * configured for single histogram fitting (fittype 0). This mode fits + * a single histogram directly without asymmetry calculation. + * + * Validates all required fields and provides default values for missing + * critical parameters with appropriate warnings. + * + * @see PGetSingleHistoRunBlockDialog For the single histogram run block dialog + */ void insertSingleHistRunBlock(); + + /** + * @brief Slot: Inserts a non-µSR RUN block via dialog. + * + * @details Launches PGetNonMusrRunBlockDialog for creating a RUN block + * configured for general x-y data fitting (fittype 8). This mode is used + * for fitting arbitrary tabulated data, not specifically µSR histograms. + * + * Validates all required fields and provides default values for missing + * critical parameters with appropriate warnings. + * + * @see PGetNonMusrRunBlockDialog For the non-µSR run block dialog + */ void insertNonMusrRunBlock(); + + /** + * @brief Slot: Inserts a default COMMANDS block. + * + * @details Inserts a standard COMMANDS block with common MINUIT commands + * for batch processing: + * - SET BATCH (suppress interactive prompts) + * - STRATEGY 1 (balance speed and accuracy) + * - MINIMIZE (perform minimization) + * - MINOS (commented out - for asymmetric errors) + * - SAVE (save parameters) + * - END RETURN (exit MINUIT) + * + * Users can edit the block after insertion to customize the fit strategy. + */ void insertCommandBlock(); + + /** + * @brief Slot: Inserts a FOURIER block via dialog. + * + * @details Launches PGetFourierBlockDialog for creating the optional + * FOURIER block that configures Fourier transform parameters for + * frequency-domain analysis of µSR data. + * + * @see PGetFourierBlockDialog For the Fourier block dialog + */ void insertFourierBlock(); + + /** + * @brief Slot: Inserts a PLOT block via dialog. + * + * @details Launches PGetPlotBlockDialog for creating the PLOT block that + * configures data visualization options including plot ranges, what to + * plot (data, theory, difference), and display options. + * + * @see PGetPlotBlockDialog For the plot block dialog + */ void insertPlotBlock(); + + /** + * @brief Slot: Inserts a default STATISTIC block. + * + * @details Inserts a STATISTIC block template with placeholder values + * for fit results. The block includes: + * - Current timestamp + * - Placeholder for chi-square value + * - Placeholder for NDF (number of degrees of freedom) + * - Placeholder for chi-square/NDF ratio + * + * After fitting, musrfit will update these placeholders with actual values. + */ void insertStatisticBlock(); private: - PAdmin *fAdmin; ///< pointer to the administration object which holds working-, executable-paths etc. + PAdmin *fAdmin; ///< Pointer to administration object with theory functions, help URLs, and configuration. }; #endif // _PSUBTEXTEDIT_H_