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

src/musredit_qt6/musredit/PGetTitleBlockDialog.cpp

@@ -27,6 +27,19 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetTitleBlockDialog.cpp
+ * @brief Implementation of the TITLE block dialog for musredit.
+ *
+ * @details Provides the implementation of PGetTitleBlockDialog class methods
+ * for creating and editing TITLE blocks in musrfit msr files. The dialog
+ * offers a straightforward text input interface for entering descriptive
+ * titles that document the purpose or content of the analysis.
+ *
+ * @author Andreas Suter
+ * @date 2010-2025
+ */
+
 #include <QMessageBox>
 #include <QDesktopServices>
 #include <QUrl>
@@ -35,9 +48,33 @@
 
 //---------------------------------------------------------------------------
 /**
- * <p>Constructor.
+ * @brief Constructor - Initializes the TITLE block dialog.
  *
- * \param helpUrl help url for the title.
+ * @details Sets up the user interface for the title input dialog. The dialog
+ * contains a single QLineEdit widget for text entry and standard OK/Cancel
+ * buttons. The interface is loaded from the UI definition file and configured
+ * as a modal dialog.
+ *
+ * The dialog is designed to be simple and focused, presenting only the
+ * essential controls needed to enter or edit a title string. No complex
+ * initialization or data loading is required beyond basic UI setup.
+ *
+ * The modal configuration ensures that users complete the title entry or
+ * explicitly cancel before returning to the main editor, preventing
+ * incomplete or ambiguous states.
+ *
+ * @param helpUrl URL string for the online help documentation. If empty, the
+ *                help button will display a placeholder message instead of
+ *                opening a web browser. The URL should point to documentation
+ *                explaining the purpose and format of msr file titles.
+ *
+ * @note The dialog does not validate the title content. Validation, if needed,
+ *       should be performed by the caller after retrieving the title via
+ *       getTitle().
+ *
+ * @see setupUi() Qt Designer generated UI initialization method
+ * @see setModal() Configures the dialog as modal
+ * @see getTitle() Retrieves the entered title after dialog acceptance
  */
 PGetTitleBlockDialog::PGetTitleBlockDialog(const QString helpUrl) : fHelpUrl(helpUrl)
 {
@@ -48,7 +85,32 @@ PGetTitleBlockDialog::PGetTitleBlockDialog(const QString helpUrl) : fHelpUrl(hel
 
 //---------------------------------------------------------------------------
 /**
- * <p>Generates a help content window showing the description of title block.
+ * @brief Opens online help documentation for TITLE blocks.
+ *
+ * @details Attempts to open the help URL in the user's default web browser using
+ * QDesktopServices::openUrl(). The help documentation typically provides:
+ * - Explanation of the TITLE block's purpose in msr files
+ * - Format specifications and constraints
+ * - Examples of well-formed titles for various analysis types
+ * - Best practices for creating informative and consistent titles
+ *
+ * Error handling:
+ * - If fHelpUrl is empty: displays an information dialog with a placeholder
+ *   message indicating that help documentation will be available in the future
+ * - If the browser fails to open: displays a critical error dialog with the URL
+ *   formatted as a clickable hyperlink, allowing users to manually copy and
+ *   paste the URL into their browser
+ *
+ * The URL is parsed in TolerantMode, which allows for flexible URL formatting
+ * and automatically handles common URL variations (e.g., with or without
+ * protocol specification).
+ *
+ * @note This slot is connected to the help button click signal in the UI.
+ * @note The dialog remains open after help is displayed, allowing users to
+ *       reference the documentation while entering the title.
+ *
+ * @see PGetTitleBlockDialog::PGetTitleBlockDialog() Where fHelpUrl is initialized
+ * @see QDesktopServices::openUrl() For the browser opening mechanism
  */
 void PGetTitleBlockDialog::helpContent()
 {

src/musredit_qt6/musredit/PGetTitleBlockDialog.h

@@ -27,6 +27,25 @@
  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  ***************************************************************************/
 
+/**
+ * @file PGetTitleBlockDialog.h
+ * @brief Dialog for creating and editing TITLE blocks in msr files.
+ *
+ * @details This header defines the PGetTitleBlockDialog class which provides
+ * a simple dialog for entering or editing the title line of a musrfit msr file.
+ * The TITLE block is optional but commonly used to provide a descriptive name
+ * or summary for the fit analysis.
+ *
+ * @author Andreas Suter
+ * @date 2010-2025
+ * @copyright Copyright (C) 2010-2025 by Andreas Suter
+ * @license GNU General Public License v2 or later
+ *
+ * @see PGetParameterBlockDialog For creating FITPARAMETER blocks
+ * @see PGetTheoryBlockDialog For creating THEORY blocks
+ * @see PGetFunctionsBlockDialog For creating FUNCTIONS blocks
+ */
+
 #ifndef _PGETTITLEBLOCKDIALOG_H_
 #define _PGETTITLEBLOCKDIALOG_H_
 
@@ -35,23 +54,104 @@
 
 //--------------------------------------------------------------------------
 /**
- * <p>Class handling the content of the menu: Edit/Add Block/Title Block.
+ * @class PGetTitleBlockDialog
+ * @brief Dialog for creating and editing TITLE blocks in msr files.
+ *
+ * @details This dialog provides a simple text input interface for entering
+ * or modifying the title of a musrfit msr file. The title serves as a
+ * descriptive label for the analysis and appears at the beginning of the
+ * msr file.
+ *
+ * @par TITLE Block Format:
+ * The TITLE block consists of a single line in the msr file:
+ * @code
+ * sample_name or_measurement_description
+ * @endcode
+ *
+ * @par Usage:
+ * The dialog is accessed through the menu: Edit → Add Block → Title Block.
+ * It presents a single-line text input field where users can enter or edit
+ * the title text. The dialog is modal, requiring user interaction before
+ * returning to the main editor.
+ *
+ * @par Example Titles:
+ * - "TF-ZF transition measurement on Cu sample at 10K"
+ * - "Longitudinal field scan H=0-2000G"
+ * - "Temperature dependence study 5-300K"
+ *
+ * @note The title is optional in msr files but recommended for documentation
+ *       purposes.
+ * @note The title should be a single line without newline characters.
+ *
+ * @see musredit Main editor application
  */
 class PGetTitleBlockDialog : public QDialog, private Ui::PGetTitleBlockDialog
 {
   Q_OBJECT
 
   public:
+    /**
+     * @brief Constructs a dialog for entering or editing a title.
+     *
+     * @details Initializes the dialog with a text input field and help button.
+     * The dialog is configured as modal to ensure user interaction completion
+     * before returning to the main editor window.
+     *
+     * @param helpUrl URL string pointing to online documentation for TITLE blocks.
+     *                If empty, the help button will display a placeholder message.
+     *
+     * @see helpContent() For the help system implementation
+     */
     PGetTitleBlockDialog(const QString helpUrl);
+
+    /**
+     * @brief Virtual destructor.
+     *
+     * @details Default destructor implementation. Qt's parent-child ownership
+     * system handles cleanup of UI elements automatically.
+     */
     virtual ~PGetTitleBlockDialog() {}
 
+    /**
+     * @brief Returns the entered title text.
+     *
+     * @details Retrieves the text currently entered in the title line edit field.
+     * This method is typically called after the dialog is accepted to obtain
+     * the title string for insertion into the msr file.
+     *
+     * @return QString containing the title text entered by the user. May be
+     *         empty if no text was entered. The returned string is trimmed
+     *         of leading/trailing whitespace by the QLineEdit widget.
+     *
+     * @note The caller should validate that the returned string does not contain
+     *       newline characters, as msr file titles must be single-line.
+     *
+     * @see QLineEdit::text() For the underlying widget method
+     */
     QString getTitle() { return fTitle_lineEdit->text(); }
 
   private slots:
+    /**
+     * @brief Opens the online help for TITLE blocks.
+     *
+     * @details Attempts to open the help URL in the system's default web browser
+     * using QDesktopServices. If the URL is empty, displays a placeholder
+     * information message. If the browser cannot be opened, shows an error
+     * dialog with the URL for manual access.
+     *
+     * The help documentation typically covers:
+     * - Purpose and format of the TITLE block
+     * - Examples of well-formed titles
+     * - Best practices for title naming
+     *
+     * @note Connected to the help button click signal in the UI.
+     *
+     * @see PGetTitleBlockDialog::PGetTitleBlockDialog() Where helpUrl is set
+     */
     void helpContent();
 
   private:
-    QString fHelpUrl; ///< help url for the asymmetry run block
+    QString fHelpUrl; ///< URL to the online documentation for TITLE blocks.
 };
 
 #endif // _PGETTITLEBLOCKDIALOG_H_