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

src/musredit_qt6/musredit/PGetAsymmetryRunBlockDialog.cpp

@@ -27,6 +27,19 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetAsymmetryRunBlockDialog.cpp
+ * @brief Implementation of the PGetAsymmetryRunBlockDialog class.
+ * @details This file implements the dialog for creating asymmetry-type RUN blocks
+ * in msr files. It handles user input validation and generates properly formatted
+ * msr-file text for all asymmetry 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,9 +52,16 @@
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * @brief Constructs the asymmetry RUN block dialog.
  *
- * \param helpUrl help url for the asymmetry run block
+ * @details Initializes the dialog UI and sets up input validators for all
+ * numeric fields. The dialog is created as modal.
+ *
+ * @par Input Validators:
+ * - Integer validators: histogram numbers, data ranges, background ranges, t0 values, packing, alpha, beta
+ * - Double validators: fixed background values, fit range
+ *
+ * @param helpUrl URL to the online documentation for asymmetry RUN blocks.
  */
 PGetAsymmetryRunBlockDialog::PGetAsymmetryRunBlockDialog(const QString helpUrl) : fHelpUrl(helpUrl)
 {
@@ -72,7 +92,14 @@ PGetAsymmetryRunBlockDialog::PGetAsymmetryRunBlockDialog(const QString helpUrl)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the run information line of the asymmetry run block.
+ * @brief Generates the RUN header line for the asymmetry 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 PGetAsymmetryRunBlockDialog::getRunHeaderInfo()
 {
@@ -88,9 +115,16 @@ QString PGetAsymmetryRunBlockDialog::getRunHeaderInfo()
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the alpha parameter for the asymmetry run block.
+ * @brief Generates the alpha parameter line for the asymmetry block.
  *
- * \param present flag indicating if the alpha parameter is used, or a default alpha==1 is going to be used.
+ * @details Alpha is the detector efficiency ratio correction parameter used in
+ * asymmetry calculations: A = (N_F - alpha * N_B) / (N_F + alpha * N_B).
+ * The parameter typically references a fit parameter number.
+ *
+ * @param[out] present Set to true if an alpha value was entered, false if empty
+ *                     (default alpha=1 will be used).
+ *
+ * @return Formatted alpha parameter string, e.g.: "alpha           1\n"
  */
 QString PGetAsymmetryRunBlockDialog::getAlphaParameter(bool &present)
 {
@@ -106,9 +140,16 @@ QString PGetAsymmetryRunBlockDialog::getAlphaParameter(bool &present)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the beta parameter for the asymmetry run block
+ * @brief Generates the beta parameter line for the asymmetry block.
  *
- * \param present flag indicating if the beta parameter is used, or a default beta==1 is going to be used.
+ * @details Beta is the detector phase correction parameter, typically used for
+ * correcting phase differences between forward and backward detectors.
+ * The parameter typically references a fit parameter number.
+ *
+ * @param[out] present Set to true if a beta value was entered, false if empty
+ *                     (default beta=1 will be used).
+ *
+ * @return Formatted beta parameter string, e.g.: "beta            1\n"
  */
 QString PGetAsymmetryRunBlockDialog::getBetaParameter(bool &present)
 {
@@ -124,9 +165,16 @@ QString PGetAsymmetryRunBlockDialog::getBetaParameter(bool &present)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the map for the asymmetry run block.
+ * @brief Generates the parameter map line for the asymmetry 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 PGetAsymmetryRunBlockDialog::getMap(bool &valid)
 {
@@ -147,10 +195,20 @@ QString PGetAsymmetryRunBlockDialog::getMap(bool &valid)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the background information for the asymmetry run block.
+ * @brief Generates the background specification for the asymmetry block.
  *
- * \param valid flag indicating if a valid background (either backgr.fix or background is given, but not both)
+ * @details Creates either a "background" line (bin ranges for background estimation)
- * is present.
+ * or a "backgr.fix" line (fixed background values). Only one type should be specified.
+ *
+ * @par Background Types:
+ * - background: Four integers specifying bin ranges [forward_start, forward_end, backward_start, backward_end]
+ * - backgr.fix: Two doubles specifying fixed background counts for forward and backward detectors
+ *
+ * @param[out] valid Set to true if valid background info is provided, false if
+ *                   no background info given (a default "background 0 10 0 10" is returned).
+ *
+ * @return Formatted background string, e.g.: "background      50   150   50   150\n"
+ *         or "backgr.fix      15.3   14.8\n"
  */
 QString PGetAsymmetryRunBlockDialog::getBackground(bool &valid)
 {
@@ -184,9 +242,17 @@ QString PGetAsymmetryRunBlockDialog::getBackground(bool &valid)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns a data range (in bins) entry for the asymmetry run block.
+ * @brief Generates the data range specification for the asymmetry block.
  *
- * \param valid flag indicating if the data entries are valid.
+ * @details Creates the "data" line specifying the histogram bin ranges to be
+ * used for fitting. Four values are required: start and end bins for both
+ * forward and backward histograms.
+ *
+ * @param[out] valid Set to true if all four data range values are provided,
+ *                   false if any are missing.
+ *
+ * @return Formatted data range string, e.g.: "data            100   8000   100   8000\n"
+ *         Returns empty string if values are missing.
  */
 QString PGetAsymmetryRunBlockDialog::getData(bool &valid)
 {
@@ -209,9 +275,15 @@ QString PGetAsymmetryRunBlockDialog::getData(bool &valid)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns a t0 parameter for the asymmetry run block.
+ * @brief Generates the T0 (time zero) specification for the asymmetry block.
  *
- * \param present flag indicating if a t0 parameter is set.
+ * @details Creates the "t0" line specifying the time zero bin for both forward
+ * and backward histograms. T0 is the bin corresponding to muon implantation time.
+ *
+ * @param[out] present Set to true if both t0 values are provided, false otherwise.
+ *
+ * @return Formatted t0 string, e.g.: "t0              250   250\n"
+ *         Returns empty string if values are missing.
  */
 QString PGetAsymmetryRunBlockDialog::getT0(bool &present)
 {
@@ -231,10 +303,15 @@ QString PGetAsymmetryRunBlockDialog::getT0(bool &present)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns a fit range entry for the asymmetry run block. If no fit range has been provided,
+ * @brief Generates the fit range specification for the asymmetry block.
- * a fit range [0,10] will be set and the valid flag will be set to false.
  *
- * \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.
+ *
+ * @param[out] valid Set to true if both fit range values are provided, false if
+ *                   missing (a default range [0.0, 10.0] is returned).
+ *
+ * @return Formatted fit range string, e.g.: "fit             0.5   9.5\n"
  */
 QString PGetAsymmetryRunBlockDialog::getFitRange(bool &valid)
 {
@@ -255,10 +332,16 @@ QString PGetAsymmetryRunBlockDialog::getFitRange(bool &valid)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>returns the packing/binning of the asymmetry run block. If no packing has been provided,
+ * @brief Generates the packing (rebinning) specification for the asymmetry block.
- * a packing of '1' will be set and the present flag will be set to false.
  *
- * \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.
+ *
+ * @param[out] present Set to true if a packing value was provided, false if
+ *                     missing (a default packing of 1 is returned).
+ *
+ * @return Formatted packing string, e.g.: "packing         10\n"
  */
 QString PGetAsymmetryRunBlockDialog::getPacking(bool &present)
 {
@@ -277,7 +360,11 @@ QString PGetAsymmetryRunBlockDialog::getPacking(bool &present)
 
 //----------------------------------------------------------------------------------------------------
 /**
- * <p>Generates a help content window showing the description of the asymmetry run block.
+ * @brief Opens the online help documentation for asymmetry 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 PGetAsymmetryRunBlockDialog::helpContent()
 {

src/musredit_qt6/musredit/PGetAsymmetryRunBlockDialog.h

@@ -27,6 +27,23 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetAsymmetryRunBlockDialog.h
+ * @brief Dialog for creating asymmetry RUN blocks in msr files.
+ * @details This header defines the PGetAsymmetryRunBlockDialog class which provides
+ * a dialog for entering parameters needed to create an asymmetry-type RUN block
+ * in a musrfit msr file. Asymmetry fitting is used for analyzing muon spin
+ * rotation data using forward and backward 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 PGetSingleHistoRunBlockDialog For single histogram RUN blocks
+ * @see PGetNonMusrRunBlockDialog For non-muSR RUN blocks
+ */
+
 #ifndef _PGETASYMMETRYRUNBLOCKDIALOG_H_
 #define _PGETASYMMETRYRUNBLOCKDIALOG_H_
 
@@ -34,7 +51,42 @@
 
 //---------------------------------------------------------------------------
 /**
- * <p>Class handling the content of the menu: Edit/Add Block/Asymmetry Run Block.
+ * @class PGetAsymmetryRunBlockDialog
+ * @brief Dialog for creating asymmetry-type RUN blocks in msr files.
+ *
+ * @details This dialog collects all parameters needed to generate an asymmetry
+ * RUN block for muon spin rotation data analysis. Asymmetry fitting uses the
+ * ratio of forward and backward detector counts to extract the muon spin
+ * polarization signal.
+ *
+ * @par RUN Block Parameters:
+ * - Run file name, beamline, institute, and file format
+ * - Forward and backward histogram numbers
+ * - Alpha parameter (detector efficiency ratio)
+ * - Beta parameter (detector phase correction)
+ * - Parameter map
+ * - Background specification (fixed or fitted)
+ * - Data range (in bins)
+ * - T0 (time zero) values
+ * - Fit range (in microseconds)
+ * - Packing/binning factor
+ *
+ * @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)
+ * alpha           1
+ * beta            1
+ * map             1 2 3
+ * forward         1
+ * backward        2
+ * background      50  150  50  150
+ * fit             0.0   10.0
+ * packing         1
+ * @endcode
+ *
+ * @see PGetSingleHistoRunBlockDialog For single histogram fitting
+ * @see PGetNonMusrRunBlockDialog For non-muSR data
  */
 class PGetAsymmetryRunBlockDialog : public QDialog, private Ui::PGetAsymmetryRunBlockDialog
 {
@@ -43,23 +95,42 @@ class PGetAsymmetryRunBlockDialog : public QDialog, private Ui::PGetAsymmetryRun
   public:
     PGetAsymmetryRunBlockDialog(const QString helpUrl);
 
+    /** @name RUN Block Generators
+     *  @brief Methods to generate formatted msr-file text for each parameter.
+     *  @{
+     */
     QString getRunHeaderInfo();
     QString getAlphaParameter(bool &present);
     QString getBetaParameter(bool &present);
     QString getMap(bool &valid);
+
+    /**
+     * @brief Get the forward histogram specification line.
+     * @return Formatted "forward" line for the msr file.
+     */
     QString getForward() { return QString("forward         " + fForwardHistoNo_lineEdit->text() + "\n"); }
+
+    /**
+     * @brief Get the backward histogram specification line.
+     * @return Formatted "backward" line for the msr file.
+     */
     QString getBackward() { return QString("backward        " + fBackwardHistoNo_lineEdit->text() + "\n"); }
+
     QString getBackground(bool &valid);
     QString getData(bool &valid);
     QString getT0(bool &present);
     QString getFitRange(bool &valid);
     QString getPacking(bool &present);
+    /** @} */
 
   private slots:
+    /**
+     * @brief Opens the online help for asymmetry RUN blocks.
+     */
     void helpContent();
 
   private:
-    QString fHelpUrl; ///< help url for the asymmetry run block
+    QString fHelpUrl; ///< URL to the online documentation for asymmetry RUN blocks.
 };
 
 #endif // _PGETASYMMETRYRUNBLOCKDIALOG_H_