From 94b3f1ac5a55b12c11ef194092d852e1510b6419 Mon Sep 17 00:00:00 2001
From: Andreas Suter <andreas.suter@psi.ch>
Date: Mon, 24 Nov 2025 10:24:36 +0100
Subject: [PATCH] improve the doxygen docu of main.cpp and musredit.h
 (musredit_qt6).

---
 src/musredit_qt6/musredit/main.cpp   |  45 ++++++++++--
 src/musredit_qt6/musredit/musredit.h | 104 ++++++++++++++++++---------
 2 files changed, 112 insertions(+), 37 deletions(-)

diff --git a/src/musredit_qt6/musredit/main.cpp b/src/musredit_qt6/musredit/main.cpp
index 09c6bf45d..ac2a331c9 100644
--- a/src/musredit_qt6/musredit/main.cpp
+++ b/src/musredit_qt6/musredit/main.cpp
@@ -27,6 +27,18 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file main.cpp
+ * @brief Entry point for the musredit application.
+ * @details This file contains the main() function which initializes the Qt
+ * application and creates the main editor window for musredit.
+ *
+ * @author Andreas Suter
+ * @date 2010-2025
+ * @copyright Copyright (C) 2010-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ */
+
 #include <iostream>
 #include <memory>
 
@@ -39,11 +51,36 @@
 #include "PFitOutputHandler.h"
 
 /**
- * <p>musredit is a simple editor based interface to the musrfit programs. It is based on Qt 4.6
- * of Digia (<code>http://qt.digia.com</code> and <code>http://qt-project.org/</code>).
+ * @brief Main entry point for the musredit application.
  *
- * <p>musredit is free software liensenced under GPL 2 or later (for detail license informations see
- * <code>http://www.gnu.org/licenses</code>).
+ * @details musredit is a simple editor-based interface to the musrfit programs,
+ * providing a graphical environment for creating, editing, and managing
+ * muon spin rotation (μSR) fit parameter files.
+ *
+ * The application is built using the Qt framework and provides the following features:
+ * - Multi-document editing of msr (muon spin rotation) parameter files
+ * - Syntax highlighting for msr file format
+ * - Integration with musrfit analysis tools (musrfit, musrview, msr2data, etc.)
+ * - Recent file tracking and session management
+ *
+ * @par Command Line Options:
+ * - No arguments: Launch the editor with an empty document
+ * - \<msr-files\>: Open the specified msr file(s) for editing
+ * - \c -h, \c --help: Display usage information and exit
+ * - \c -v, \c --version: Display version/git revision information and exit
+ *
+ * @par License:
+ * musredit is free software licensed under GPL v2 or later.
+ * See http://www.gnu.org/licenses for details.
+ *
+ * @param argc Number of command-line arguments
+ * @param argv Array of command-line argument strings
+ *
+ * @return 0 on successful execution or when displaying help/version,
+ *         or the Qt application exit code from QApplication::exec()
+ *
+ * @see PTextEdit The main editor window class
+ * @see https://qt.io Qt framework documentation
  */
 int main( int argc, char ** argv ) 
 {
diff --git a/src/musredit_qt6/musredit/musredit.h b/src/musredit_qt6/musredit/musredit.h
index 01861c247..377a5e408 100644
--- a/src/musredit_qt6/musredit/musredit.h
+++ b/src/musredit_qt6/musredit/musredit.h
@@ -27,56 +27,94 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file musredit.h
+ * @brief Common definitions and data structures for the musredit application.
+ * @details This header file contains shared constants, data structures, and type
+ * definitions used throughout the musredit application. It defines structures
+ * for msr2data parameter handling and find/replace operations.
+ *
+ * @author Andreas Suter
+ * @date 2010-2025
+ * @copyright Copyright (C) 2010-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ */
+
 #ifndef _MUSREDIT_H_
 #define _MUSREDIT_H_
 
 #include <QString>
 
+/**
+ * @def MAX_RECENT_FILES
+ * @brief Maximum number of recently opened files to track.
+ * @details This constant defines the maximum number of entries in the
+ * "Recent Files" menu. When this limit is exceeded, the oldest entry
+ * is removed to make room for new entries.
+ */
 #define MAX_RECENT_FILES 5
 
 //-------------------------------------------------------------------------------------------------
 /**
- * <p> This structure is used in conjunction to <code>msr2data</code>. It stores the necessary
- * parameters to handle <code>msr2data</code>. For a detailed description of the meaning of these
- * parameters see <code>msr2data --help</code> and the online documentation.
+ * @struct PMsr2DataParam
+ * @brief Parameter structure for msr2data tool integration.
+ *
+ * @details This structure holds all the configuration parameters needed to invoke
+ * the msr2data tool from within musredit. The msr2data tool is used to:
+ * - Generate msr files from templates for multiple runs
+ * - Perform batch fitting operations
+ * - Export fit parameters to database (db) files or column-formatted ASCII files
+ *
+ * For a detailed description of these parameters, see the msr2data documentation
+ * (\c msr2data \c --help) and the online musrfit user manual.
+ *
+ * @see https://lmu.web.psi.ch/musrfit/user/html/user-manual.html#msr2data msr2data documentation
  */
 struct PMsr2DataParam {
-  QString runList;             ///< list of run numbers (usage 3 of msr2data)
-  QString runListFileName;     ///< run list filename (usage 4 of msr2data)
-  QString msrFileExtension;    ///< msr filename extension, e.g. '0100_h13.msr' -> '_h13'
-  int templateRunNo;           ///< fit template run number
-  QString paramList;           ///< parameter list to be exported.
-  QString dbOutputFileName;    ///< output file name for the generated (trumf-like) db-file.
-  bool writeDbHeader;          ///< flag indicating if a db header shall be generated (== !noheader in msr2data)
-  bool ignoreDataHeaderInfo;   ///< flag indicating if data header info (like temp.) shall be ignored (== nosummary in msr2data)
-  bool keepMinuit2Output;      ///< flag indicating if the minuit2 output shall be kept ('-k' in msr2data)
-  bool writeColumnData;        ///< flag indicating if instead of a db-file a column data ascii file shall be written ('data' in msr2data)
-  bool recreateDbFile;         ///< flag: true = recreate db-file, false = append to present db-file
-  bool chainFit;               ///< flag: true = chain fit, i.e. the template for a fit is the preceeding run. false = the template is always the source for the new msr-file
-  bool openFilesAfterFitting;  ///< flag: true = open msr-file after fit in musredit. false = do not open msr-file after fit.
-  bool titleFromDataFile;      ///< flag indicating if the title for the msr-file shall be extracted from the data-file ('-t' in msr2data)
-  bool estimateN0;             ///< flag indicating if the N0 shall be estimated for single histogram fitting
-  bool yamlOut;                ///< flag indicating if the MINUIT2.OUTPUT content should be written to <msr-file>.yaml
-  bool perRunBlockChisq;       ///< flag indicating if per-run-block-chisq shall be dumped into the msr-file
-  bool createMsrFileOnly;      ///< flag: true = just create the msr-files without any fitting ('msr-<template>' in msr2data)
-  bool fitOnly;                ///< flag: true = just perform the fits wihtout generating any msr-files ('fit' in msr2data).
-  bool global;                 ///< flag: true = 'global' option
-  bool globalPlus;             ///< flag: true = 'global+' option
+  QString runList;             ///< Space-separated list of run numbers for batch processing (msr2data usage 3).
+  QString runListFileName;     ///< Path to a file containing run numbers, one per line (msr2data usage 4).
+  QString msrFileExtension;    ///< Optional extension appended to msr filenames (e.g., "_h13" for "0100_h13.msr").
+  int templateRunNo;           ///< Run number of the template msr file to use as base for new files.
+  QString paramList;           ///< Comma-separated list of parameter names/numbers to export to db-file.
+  QString dbOutputFileName;    ///< Output filename for the generated TRIUMF-style database file.
+  bool writeDbHeader;          ///< If true, include header in db-file output (opposite of msr2data's \c noheader flag).
+  bool ignoreDataHeaderInfo;   ///< If true, skip summary info extraction from data headers (msr2data \c nosummary flag).
+  bool keepMinuit2Output;      ///< If true, preserve MINUIT2.OUTPUT/MINUIT2.root files (msr2data \c -k flag).
+  bool writeColumnData;        ///< If true, write column-formatted ASCII instead of db-file (msr2data \c data option).
+  bool recreateDbFile;         ///< If true, overwrite existing db-file; if false, append to it.
+  bool chainFit;               ///< If true, use previous run's fit result as template for next run (chain fitting mode).
+  bool openFilesAfterFitting;  ///< If true, automatically open fitted msr-files in musredit after completion.
+  bool titleFromDataFile;      ///< If true, extract msr-file title from the data file (msr2data \c -t flag).
+  bool estimateN0;             ///< If true, estimate N0 parameter for single histogram fits.
+  bool yamlOut;                ///< If true, write MINUIT2 output to \<msr-file\>.yaml format.
+  bool perRunBlockChisq;       ///< If true, include per-run-block chi-square values in msr-file output.
+  bool createMsrFileOnly;      ///< If true, only generate msr-files without performing fits (msr2data \c msr-\<template\>).
+  bool fitOnly;                ///< If true, only perform fits using existing msr-files (msr2data \c fit option).
+  bool global;                 ///< If true, enable global fitting mode (msr2data \c global option).
+  bool globalPlus;             ///< If true, enable global+ fitting mode with enhanced constraints (msr2data \c global+ option).
 };
 
 //-------------------------------------------------------------------------------------------------
 /**
- * This structure is used to handle find (and replace) within <code>musredit</code> properly.
+ * @struct PFindReplaceData
+ * @brief Configuration structure for find and replace operations.
+ *
+ * @details This structure stores all parameters needed to perform find and replace
+ * operations within the musredit text editor. It captures the search/replace strings
+ * as well as various options that control how the search is performed.
+ *
+ * The structure is typically populated from the Find/Replace dialog and used
+ * by the editor's search functionality.
  */
 struct PFindReplaceData {
-  QString findText;     ///< text to be found
-  QString replaceText;  ///< replacement string
-  bool caseSensitive;   ///< true = case sensitive
-  bool wholeWordsOnly;  ///< true = look for whole words only
-  bool fromCursor;      ///< true = start the find/replace form the cursor position only
-  bool findBackwards;   ///< true = reversed search
-  bool selectedText;    ///< true = handle only the selected text
-  bool promptOnReplace; ///< true = request on OK from the user before performing the replace action
+  QString findText;     ///< Text pattern to search for in the document.
+  QString replaceText;  ///< Replacement string to substitute for found matches.
+  bool caseSensitive;   ///< If true, search is case-sensitive (e.g., "Run" != "run").
+  bool wholeWordsOnly;  ///< If true, match only complete words (not substrings).
+  bool fromCursor;      ///< If true, search starts from cursor position; otherwise from document start.
+  bool findBackwards;   ///< If true, search proceeds backward through the document.
+  bool selectedText;    ///< If true, limit search/replace to the currently selected text only.
+  bool promptOnReplace; ///< If true, prompt user for confirmation before each replacement.
 };
 
 #endif // _MUSREDIT_H_