diff --git a/src/musredit_qt6/musredit/PMusrEditAbout.cpp b/src/musredit_qt6/musredit/PMusrEditAbout.cpp index 88186bbb8..859ae6a4f 100644 --- a/src/musredit_qt6/musredit/PMusrEditAbout.cpp +++ b/src/musredit_qt6/musredit/PMusrEditAbout.cpp @@ -27,6 +27,22 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PMusrEditAbout.cpp + * @brief Implementation of the musredit About dialog. + * + * @details Provides the implementation of the PMusrEditAbout class which + * displays comprehensive version and build information for the musredit + * application. The dialog retrieves version details from various build-time + * configuration headers and presents them in a user-friendly format. + * + * Version information includes package version, ROOT framework version, + * build configuration, and git repository details (when available). + * + * @author Andreas Suter + * @date 2010-2025 + */ + #include "config.h" #ifdef HAVE_GIT_REV_H #include "git-revision.h" @@ -35,7 +51,68 @@ //--------------------------------------------------------------------------- /** - *

Handles the musredit about popup. + * @brief Constructor - Initializes and populates the About dialog. + * + * @details Sets up the About dialog user interface and dynamically populates + * all version information labels with current build details. The dialog + * retrieves information from various sources and presents it in a clear, + * structured format. + * + * **Initialization Process:** + * + * 1. **UI Setup**: Loads the dialog layout from Qt Designer UI file via setupUi() + * + * 2. **Git Information**: Conditionally populates git-related fields based on + * availability of git-revision.h header: + * - If HAVE_GIT_REV_H is defined: + * - Displays actual git branch from GIT_BRANCH macro + * - Displays commit SHA1 hash from GIT_CURRENT_SHA1 macro + * - If not defined: + * - Displays "unknown" for both branch and revision + * - Typical for release builds or non-git source distributions + * + * 3. **Package Version**: Combines musrfit package information: + * - PACKAGE_VERSION: Version string (e.g., "1.9.3") + * - BUILD_TYPE: Build configuration ("Debug" or "Release") + * - Format: "musrfit-version: 1.9.3 (Release)" + * + * 4. **ROOT Version**: Displays ROOT framework version from ROOT_VERSION_USED macro + * - Format: "ROOT-version: 6.28/00" (or current ROOT version) + * + * 5. **Modal Configuration**: Sets the dialog as modal to ensure user + * acknowledgment before continuing with the application + * + * **Version Information Sources:** + * - config.h: PACKAGE_VERSION, BUILD_TYPE, ROOT_VERSION_USED + * - git-revision.h: GIT_BRANCH, GIT_CURRENT_SHA1 (conditional) + * + * **Example Dialog Content:** + * @code + * musrfit-version: 1.9.3 (Release) + * ROOT-version: 6.28/00 + * git-branch: main + * git-rev: a1b2c3d4e5f6... + * @endcode + * + * @param parent Pointer to the parent widget, typically the main application + * window. If nullptr, the dialog has no parent and will not + * center over any window. The Qt parent-child relationship + * ensures: + * - Automatic memory management when parent is destroyed + * - Proper dialog centering over parent window + * - Inheritance of default font and style settings + * + * @note The git information is particularly useful for bug reports, allowing + * developers to identify the exact source code version. + * @note All macros (PACKAGE_VERSION, BUILD_TYPE, etc.) are defined at compile + * time by the build system (CMake). + * @note The dialog remains centered even if the parent window is moved after + * the dialog is shown. + * + * @see config.h For PACKAGE_VERSION, BUILD_TYPE, and ROOT_VERSION_USED definitions + * @see git-revision.h For GIT_BRANCH and GIT_CURRENT_SHA1 definitions (optional) + * @see setupUi() Qt Designer generated UI initialization + * @see setModal() Configures modal dialog behavior */ PMusrEditAbout::PMusrEditAbout(QWidget *parent) : QDialog(parent) { diff --git a/src/musredit_qt6/musredit/PMusrEditAbout.h b/src/musredit_qt6/musredit/PMusrEditAbout.h index 7627b061b..01e10ce02 100644 --- a/src/musredit_qt6/musredit/PMusrEditAbout.h +++ b/src/musredit_qt6/musredit/PMusrEditAbout.h @@ -27,18 +27,111 @@ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ +/** + * @file PMusrEditAbout.h + * @brief About dialog for the musredit application. + * + * @details This header defines the PMusrEditAbout class which provides an + * "About" dialog displaying version information and build details for the + * musredit application. The dialog shows musrfit package version, ROOT + * version, build type, and git repository information. + * + * @author Andreas Suter + * @date 2010-2025 + * @copyright Copyright (C) 2010-2025 by Andreas Suter + * @license GNU General Public License v2 or later + * + * @see musredit Main editor application + */ + #ifndef _PMUSREDITABOUT_H_ #define _PMUSREDITABOUT_H_ #include "musredit.h" #include "ui_PMusrEditAbout.h" +/** + * @class PMusrEditAbout + * @brief About dialog displaying version and build information. + * + * @details This dialog presents comprehensive version and build information + * for the musredit application. It is typically accessed through the Help menu + * and provides users with essential details for bug reporting and version + * verification. + * + * @par Displayed Information: + * The dialog displays the following information: + * - **musrfit package version**: Version number from PACKAGE_VERSION macro + * - **Build type**: Debug or Release build configuration + * - **ROOT version**: Version of ROOT framework used for building + * - **Git branch**: Source code branch name (if available) + * - **Git revision**: Current commit SHA1 hash (if available) + * + * @par Version Information Sources: + * Version information is obtained from: + * - config.h: PACKAGE_VERSION and BUILD_TYPE macros + * - git-revision.h: GIT_BRANCH and GIT_CURRENT_SHA1 (if HAVE_GIT_REV_H defined) + * - ROOT configuration: ROOT_VERSION_USED macro + * + * @par Git Information Availability: + * Git branch and revision information are only available if: + * - The application was built from a git repository + * - The HAVE_GIT_REV_H preprocessor symbol is defined + * - The git-revision.h header was generated during build + * + * If git information is unavailable, "unknown" is displayed for both branch + * and revision fields. + * + * @note The dialog is modal, requiring user dismissal before returning to + * the main application. + * @note Typical usage: Help → About musredit menu action + * + * @see musredit For the main application class + */ class PMusrEditAbout : public QDialog, private Ui::PMusrEditAbout { Q_OBJECT public: + /** + * @brief Constructs the About dialog. + * + * @details Initializes the About dialog and populates all version information + * labels with current build details. The dialog layout is loaded from the + * Qt Designer UI file, and text labels are dynamically updated with version + * information from build-time configuration macros. + * + * Version information population: + * - Git information is conditionally displayed based on HAVE_GIT_REV_H + * - musrfit version combines PACKAGE_VERSION and BUILD_TYPE + * - ROOT version is obtained from ROOT_VERSION_USED macro + * + * The dialog is configured as modal to ensure users acknowledge the + * information before continuing. + * + * @param parent Pointer to the parent widget (typically the main window). + * If nullptr, the dialog has no parent. The parent-child + * relationship ensures proper dialog lifetime management + * and centering over the parent window. + * + * @note The dialog centers itself over the parent window if a parent is provided. + * @note All version labels are set with monospace-friendly formatting. + * + * @see setupUi() Qt Designer generated UI initialization method + * @see setModal() Configures the dialog as modal + */ PMusrEditAbout(QWidget *parent = nullptr); + + /** + * @brief Virtual destructor. + * + * @details Default destructor implementation. Qt's parent-child ownership + * system automatically handles cleanup of UI elements created by setupUi(). + * No manual cleanup is required. + * + * @note Declared virtual to ensure proper cleanup in inheritance hierarchies, + * though this class is typically used directly without subclassing. + */ virtual ~PMusrEditAbout() {} };