improve the doxygen docu of PMusrEditAbout.* (musredit_qt6).
This commit is contained in:
@@ -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 @@
|
||||
|
||||
//---------------------------------------------------------------------------
|
||||
/**
|
||||
* <p>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)
|
||||
{
|
||||
|
||||
@@ -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() {}
|
||||
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user