improve the doxygen docu of PGetSingleHistoRunBlockDialog.* (musredit_qt6).

src/musredit_qt6/musredit/PGetSingleHistoRunBlockDialog.cpp

@@ -27,6 +27,19 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetSingleHistoRunBlockDialog.cpp
+ * @brief Implementation of the PGetSingleHistoRunBlockDialog class.
+ * @details This file implements the dialog for creating single histogram type
+ * RUN blocks in msr files. It handles user input validation and generates
+ * properly formatted msr-file text for all single histogram RUN block parameters.
+ *
+ * @author Andreas Suter
+ * @date 2009-2025
+ * @copyright Copyright (C) 2009-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ */
+
 #include <QLineEdit>
 #include <QValidator>
 #include <QComboBox>
@@ -39,10 +52,21 @@
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * @brief Constructs the single histogram RUN block dialog.
  *
- * \param helpUrl help url for the asymmetry run block
- * \param lifetimeCorrection flag indicating if lifetime correction shall be enabled.
+ * @details Initializes the dialog UI and sets up input validators for all
+ * numeric fields. The dialog is created as modal. The lifetime correction
+ * checkbox is initialized based on the provided parameter.
+ *
+ * @par Input Validators:
+ * - Integer validators: histogram number, norm, data range, background range,
+ *   background fit parameter, packing, t0, lifetime parameter
+ * - Double validators: fixed background value, fit range
+ *
+ * @param helpUrl URL to the online documentation for single histogram RUN blocks.
+ *                Defaults to empty string if not provided.
+ * @param lifetimeCorrection Initial state of the lifetime correction checkbox.
+ *                           Defaults to true (enabled).
  */
 PGetSingleHistoRunBlockDialog::PGetSingleHistoRunBlockDialog(const QString helpUrl,
                                                              const bool lifetimeCorrection) : fHelpUrl(helpUrl)
@@ -69,7 +93,14 @@ PGetSingleHistoRunBlockDialog::PGetSingleHistoRunBlockDialog(const QString helpU
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the run information line of the single histogram run block.
+ * @brief Generates the RUN header line for the single histogram block.
+ *
+ * @details Creates the first line of the RUN block containing the run file name,
+ * beamline identifier, institute name, and data file format. The beamline is
+ * converted to uppercase.
+ *
+ * @return Formatted RUN header string, e.g.:
+ *         "RUN data001 GPS PSI ROOT   (name beamline institute data-file-format)\\n"
  */
 QString PGetSingleHistoRunBlockDialog::getRunHeaderInfo()
 {
@@ -85,9 +116,16 @@ QString PGetSingleHistoRunBlockDialog::getRunHeaderInfo()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the map for the single histogram run block.
+ * @brief Generates the parameter map line for the single histogram block.
  *
- * \param valid flag indicating if the map is potentially valid.
+ * @details The map line defines the mapping between theory function parameters
+ * and the fit parameters defined in the FITPARAMETER block. It should contain
+ * only space-separated integers.
+ *
+ * @param[out] valid Set to true if the map contains only digits and spaces,
+ *                   false if invalid characters are found.
+ *
+ * @return Formatted map string, e.g.: "map             1 2 3 4\\n"
  */
 QString PGetSingleHistoRunBlockDialog::getMap(bool &valid)
 {
@@ -108,9 +146,16 @@ QString PGetSingleHistoRunBlockDialog::getMap(bool &valid)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns a data range (in bins) entry for the single histogram run block.
+ * @brief Generates the data range specification for the single histogram block.
  *
- * \param valid flag indicating if the data entries are valid.
+ * @details Creates the "data" line specifying the histogram bin range to be
+ * used for fitting. Both start and end bins are required.
+ *
+ * @param[out] valid Set to true if both data range values are provided,
+ *                   false if either is missing.
+ *
+ * @return Formatted data range string, e.g.: "data            100   8000\\n"
+ *         Returns empty string if values are missing.
  */
 QString PGetSingleHistoRunBlockDialog::getData(bool &valid)
 {
@@ -130,10 +175,23 @@ QString PGetSingleHistoRunBlockDialog::getData(bool &valid)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the background information for the single histogram run block.
+ * @brief Generates the background specification for the single histogram block.
  *
- * \param valid flag indicating if a valid background (either backgr.fix, background, or backgr.fit is given, but only one)
- * is present.
+ * @details Creates either a "background" line (bin ranges for background estimation),
+ * "backgr.fix" line (fixed background value), or "backgr.fit" line (fit parameter
+ * for background). Only one type should be specified; if multiple are provided,
+ * the last one takes precedence.
+ *
+ * @par Background Types:
+ * - **background**: Two integers specifying bin range [start, end] for background estimation
+ * - **backgr.fix**: One double specifying fixed background counts per bin
+ * - **backgr.fit**: One integer specifying the fit parameter number for background
+ *
+ * @param[out] valid Set to true if valid background info is provided, false if
+ *                   no background info given (a default "background 0 10" is returned).
+ *
+ * @return Formatted background string, e.g.: "background      50   100\\n"
+ *         or "backgr.fix      15.3\\n" or "backgr.fit      5\\n"
  */
 QString PGetSingleHistoRunBlockDialog::getBackground(bool &valid)
 {
@@ -168,10 +226,16 @@ QString PGetSingleHistoRunBlockDialog::getBackground(bool &valid)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns a fit range entry for the single histogram run block. If no fit range has been provided,
- * a fit range [0,10] will be set and the valid flag will be set to false.
+ * @brief Generates the fit range specification for the single histogram block.
  *
- * \param valid flag indicating if a fit range was provided.
+ * @details Creates the "fit" line specifying the time range (in microseconds)
+ * over which the fit will be performed. If no fit range is provided by the user,
+ * a default range of [0.0, 10.0] is returned.
+ *
+ * @param[out] valid Set to true if both fit range values are provided by the user,
+ *                   false if using the default range.
+ *
+ * @return Formatted fit range string, e.g.: "fit             0.5   9.5\\n"
  */
 QString PGetSingleHistoRunBlockDialog::getFitRange(bool &valid)
 {
@@ -192,10 +256,16 @@ QString PGetSingleHistoRunBlockDialog::getFitRange(bool &valid)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the packing/binning of the single histogram run block. If no packing has been provided,
- * a packing of '1' will be set and the present flag will be set to false.
+ * @brief Generates the packing (rebinning) specification for the single histogram block.
  *
- * \param present flag indicating if a packing parameter was provided.
+ * @details Creates the "packing" line specifying how many histogram bins should
+ * be combined into one. A packing of 1 means no rebinning, 2 means combine
+ * pairs of bins, etc. If no packing is provided, a default value of 1 is used.
+ *
+ * @param[out] present Set to true if a packing value was provided by the user,
+ *                     false if using the default value.
+ *
+ * @return Formatted packing string, e.g.: "packing         10\\n"
  */
 QString PGetSingleHistoRunBlockDialog::getPacking(bool &present)
 {
@@ -214,9 +284,15 @@ QString PGetSingleHistoRunBlockDialog::getPacking(bool &present)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns a t0 parameter for the single histogram run block.
+ * @brief Generates the T0 (time zero) specification for the single histogram block.
  *
- * \param present flag indicating if a t0 parameter is set.
+ * @details Creates the "t0" line specifying the time zero bin for the histogram.
+ * T0 is the bin corresponding to muon implantation time. This parameter is optional.
+ *
+ * @param[out] present Set to true if a t0 value was provided, false if not specified.
+ *
+ * @return Formatted t0 string, e.g.: "t0              250\\n"
+ *         Returns empty string if t0 is not specified.
  */
 QString PGetSingleHistoRunBlockDialog::getT0(bool &present)
 {
@@ -235,9 +311,16 @@ QString PGetSingleHistoRunBlockDialog::getT0(bool &present)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the muon lifetime parameter if present.
+ * @brief Generates the muon lifetime parameter line for the single histogram block.
  *
- * \param present flag indicating if a muon life time parameter has been present.
+ * @details Creates the "lifetime" line specifying which fit parameter contains
+ * the muon lifetime value. This is used when the muon lifetime should be fitted
+ * rather than using the fixed standard value. This parameter is optional.
+ *
+ * @param[out] present Set to true if a lifetime parameter was provided, false otherwise.
+ *
+ * @return Formatted lifetime string, e.g.: "lifetime        3\\n"
+ *         Returns empty string if lifetime parameter is not specified.
  */
 QString PGetSingleHistoRunBlockDialog::getMuonLifetimeParam(bool &present)
 {
@@ -256,9 +339,15 @@ QString PGetSingleHistoRunBlockDialog::getMuonLifetimeParam(bool &present)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the lifetime correction flag.
+ * @brief Generates the lifetime correction flag for the single histogram block.
  *
- * \param present flag showing if the lifetime correction flag should be set.
+ * @details Creates the "lifetimecorrection" line if the checkbox is enabled.
+ * When present, musrfit will apply muon lifetime correction to the data,
+ * effectively removing the exponential decay component from the signal.
+ *
+ * @param[out] present Set to true if lifetime correction is enabled, false otherwise.
+ *
+ * @return "lifetimecorrection\\n" if enabled, empty string if disabled.
  */
 QString PGetSingleHistoRunBlockDialog::getLifetimeCorrection(bool &present)
 {
@@ -276,7 +365,11 @@ QString PGetSingleHistoRunBlockDialog::getLifetimeCorrection(bool &present)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Generates a help content window showing the description of the single histogram run block.
+ * @brief Opens the online help documentation for single histogram RUN blocks.
+ *
+ * @details Attempts to open the help URL in the system's default web browser
+ * using QDesktopServices. If the URL is empty, displays an informational message.
+ * If the browser fails to open, displays an error message with a clickable link.
  */
 void PGetSingleHistoRunBlockDialog::helpContent()
 {

src/musredit_qt6/musredit/PGetSingleHistoRunBlockDialog.h

@@ -27,6 +27,23 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetSingleHistoRunBlockDialog.h
+ * @brief Dialog for creating single histogram RUN blocks in msr files.
+ * @details This header defines the PGetSingleHistoRunBlockDialog class which provides
+ * a dialog for entering parameters needed to create a single histogram type RUN block
+ * in a musrfit msr file. Single histogram fitting analyzes individual detector histograms
+ * rather than asymmetry between detector pairs.
+ *
+ * @author Andreas Suter
+ * @date 2009-2025
+ * @copyright Copyright (C) 2009-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ *
+ * @see PGetAsymmetryRunBlockDialog For asymmetry RUN blocks
+ * @see PGetNonMusrRunBlockDialog For non-muSR RUN blocks
+ */
+
 #ifndef _PGETSINGLEHISTORUNBLOCKDIALOG_H_
 #define _PGETSINGLEHISTORUNBLOCKDIALOG_H_
 
@@ -35,9 +52,51 @@
 
 #include "ui_PGetSingleHistoRunBlockDialog.h"
 
-//--------------------------------------------------------------------------
+//---------------------------------------------------------------------------
 /**
- * <p>Class handling the content of the menu: Edit/Add Block/Single Histo Run Block.
+ * @class PGetSingleHistoRunBlockDialog
+ * @brief Dialog for creating single histogram type RUN blocks in msr files.
+ *
+ * @details This dialog collects all parameters needed to generate a single
+ * histogram RUN block for muon spin rotation data analysis. Single histogram
+ * fitting is used when analyzing individual detector counts rather than
+ * computing asymmetry from forward/backward detector pairs.
+ *
+ * @par RUN Block Parameters:
+ * - Run file name, beamline, institute, and file format
+ * - Forward histogram number
+ * - Normalization parameter
+ * - Parameter map
+ * - Data range (in bins)
+ * - Background specification (fixed, fitted, or estimated from bins)
+ * - T0 (time zero) value
+ * - Fit range (in microseconds)
+ * - Packing/binning factor
+ * - Muon lifetime parameter
+ * - Lifetime correction flag
+ *
+ * @par Generated Output Format:
+ * The dialog generates msr-file formatted text blocks such as:
+ * @code
+ * RUN data001 GPS PSI ROOT   (name beamline institute data-file-format)
+ * map             1 2 3
+ * forward         1
+ * norm            1
+ * data            100   8000
+ * background      50   100
+ * t0              250
+ * fit             0.0   10.0
+ * packing         1
+ * @endcode
+ *
+ * @par Background Options:
+ * Three mutually exclusive background specification methods:
+ * - **background**: Bin range for background estimation [start, end]
+ * - **backgr.fix**: Fixed background value (counts per bin)
+ * - **backgr.fit**: Fit parameter number for background
+ *
+ * @see PGetAsymmetryRunBlockDialog For asymmetry fitting with detector pairs
+ * @see PGetNonMusrRunBlockDialog For non-muSR generic data
  */
 class PGetSingleHistoRunBlockDialog : public QDialog, private Ui::PGetSingleHistoRunBlockDialog
 {
@@ -46,10 +105,25 @@ class PGetSingleHistoRunBlockDialog : public QDialog, private Ui::PGetSingleHist
   public:
     PGetSingleHistoRunBlockDialog(const QString helpUrl = "", const bool lifetimeCorrection = true);
 
+    /** @name RUN Block Generators
+     *  @brief Methods to generate formatted msr-file text for each parameter.
+     *  @{
+     */
     QString getRunHeaderInfo();
     QString getMap(bool &valid);
+
+    /**
+     * @brief Gets the forward histogram specification line.
+     * @return Formatted "forward" line for the msr file.
+     */
     QString getForward() { return QString("forward         " + fForwardHistoNo_lineEdit->text() + "\n"); }
+
+    /**
+     * @brief Gets the normalization parameter line.
+     * @return Formatted "norm" line for the msr file.
+     */
     QString getNorm() { return QString("norm            " + fNorm_lineEdit->text() + "\n"); }
+
     QString getData(bool &valid);
     QString getBackground(bool &valid);
     QString getFitRange(bool &valid);
@@ -57,12 +131,16 @@ class PGetSingleHistoRunBlockDialog : public QDialog, private Ui::PGetSingleHist
     QString getT0(bool &present);
     QString getMuonLifetimeParam(bool &present);
     QString getLifetimeCorrection(bool &present);
+    /** @} */
 
   private slots:
+    /**
+     * @brief Opens the online help for single histogram RUN blocks.
+     */
     void helpContent();
 
   private:
-    QString fHelpUrl; ///< help url for the asymmetry run block
+    QString fHelpUrl; ///< URL to the online documentation for single histogram RUN blocks.
 };
 
 #endif // _PGETSINGLEHISTORUNBLOCKDIALOG_H_