diff --git a/progressfeedback.cpp b/progressfeedback.cpp index f5aaf72..065291e 100644 --- a/progressfeedback.cpp +++ b/progressfeedback.cpp @@ -3,4 +3,22 @@ using namespace std; namespace TagParser { -} + +/*! + * \class BasicProgressFeedback + * \brief The BasicProgressFeedback class provides the base for ProgressFeedback and AbortableProgressFeedback. + * \remarks Don't use this class directly. Use ProgressFeedback or AbortableProgressFeedback instead. + */ + +/*! + * \class ProgressFeedback + * \brief The ProgressFeedback class provides feedback about an ongoing operation via callbacks. + */ + +/*! + * \class AbortableProgressFeedback + * \brief The AbortableProgressFeedback class provides feedback about an ongoing operation via callbacks. + * It also allows to abort the operation. + */ + +} // namespace TagParser diff --git a/progressfeedback.h b/progressfeedback.h index d17eef9..7c83cb5 100644 --- a/progressfeedback.h +++ b/progressfeedback.h @@ -35,6 +35,11 @@ private: byte m_overallPercentage; }; +/*! + * \brief Constructs a new BasicProgressFeedback. + * + * It will call \a callback on the next step and \a percentageOnlyCallback when only the percentage changes. + */ template inline BasicProgressFeedback::BasicProgressFeedback(const Callback &callback, const Callback &percentageOnlyCallback) : m_callback(callback) @@ -44,6 +49,11 @@ inline BasicProgressFeedback::BasicProgressFeedback(cons { } +/*! + * \brief Constructs a new BasicProgressFeedback. + * + * It will call \a callback on the next step and \a percentageOnlyCallback when only the percentage changes. + */ template inline BasicProgressFeedback::BasicProgressFeedback(Callback &&callback, Callback &&percentageOnlyCallback) : m_callback(callback) @@ -53,21 +63,36 @@ inline BasicProgressFeedback::BasicProgressFeedback(Call { } +/*! + * \brief Returns the name of the current step (initially empty). + */ template inline const std::string &BasicProgressFeedback::step() const { return m_step; } +/*! + * \brief Returns the percentage of the current step (initially 0, supposed to be a value from 0 to 100). + * \remarks A percentage of 0 means that the percentage is currently unknown; 100 means finished. + */ template inline byte BasicProgressFeedback::stepPercentage() const { return m_stepPercentage; } +/*! + * \brief Returns the overall percentage (initially 0, supposed to be a value from 0 to 100). + * \remarks A percentage of 0 means that the percentage is currently unknown; 100 means finished. + */ template inline byte BasicProgressFeedback::overallPercentage() const { return m_overallPercentage; } +/*! + * \brief Updates the current step and invokes the first callback specified on construction. + * \remarks Supposed to be called only by the operation itself. + */ template inline void BasicProgressFeedback::updateStep(const std::string &step, byte stepPercentage) { @@ -78,6 +103,10 @@ inline void BasicProgressFeedback::updateStep(const std: } } +/*! + * \brief Updates the current step and invokes the first callback specified on construction. + * \remarks Supposed to be called only by the operation itself. + */ template inline void BasicProgressFeedback::updateStep(std::string &&step, byte stepPercentage) { @@ -88,6 +117,10 @@ inline void BasicProgressFeedback::updateStep(std::strin } } +/*! + * \brief Updates the current step percentage and invokes the second callback specified on construction (or the first if only one has been specified). + * \remarks Supposed to be called only by the operation itself. + */ template inline void BasicProgressFeedback::updateStepPercentage(byte stepPercentage) { m_stepPercentage = stepPercentage; @@ -98,12 +131,21 @@ template inline void BasicProgressFeedback inline void BasicProgressFeedback::updateStepPercentageFromFraction(double stepPercentage) { updateStepPercentage(static_cast(stepPercentage * 100.0)); } +/*! + * \brief Updates the overall percentage and invokes the second callback specified on construction (or the first if only one has been specified). + * \remarks Supposed to be called only by the operation itself. + */ template inline void BasicProgressFeedback::updateOverallPercentage(byte overallPercentage) { m_overallPercentage = overallPercentage; @@ -120,11 +162,21 @@ public: ProgressFeedback(Callback &&callback, Callback &&percentageOnlyCallback = Callback()); }; +/*! + * \brief Constructs a new ProgressFeedback. + * + * It will call \a callback on the next step and \a percentageOnlyCallback when only the percentage changes. + */ inline ProgressFeedback::ProgressFeedback(const Callback &callback, const Callback &percentageOnlyCallback) : BasicProgressFeedback(callback, percentageOnlyCallback) { } +/*! + * \brief Constructs a new ProgressFeedback. + * + * It will call \a callback on the next step and \a percentageOnlyCallback when only the percentage changes. + */ inline ProgressFeedback::ProgressFeedback(Callback &&callback, Callback &&percentageOnlyCallback) : BasicProgressFeedback(callback, percentageOnlyCallback) { @@ -145,28 +197,50 @@ private: std::atomic_bool m_aborted; }; +/*! + * \brief Constructs a new AbortableProgressFeedback. + * + * It will call \a callback on the next step and \a percentageOnlyCallback when only the percentage changes. + */ inline AbortableProgressFeedback::AbortableProgressFeedback(const Callback &callback, const Callback &percentageOnlyCallback) : BasicProgressFeedback(callback, percentageOnlyCallback) , m_aborted(false) { } +/*! + * \brief Constructs a new AbortableProgressFeedback. + * + * It will call \a callback on the next step and \a percentageOnlyCallback when only the percentage changes. + */ inline AbortableProgressFeedback::AbortableProgressFeedback(Callback &&callback, Callback &&percentageOnlyCallback) : BasicProgressFeedback(callback, percentageOnlyCallback) , m_aborted(false) { } +/*! + * \brief Returns whether the operation has been aborted via tryToAbort(). + */ inline bool AbortableProgressFeedback::isAborted() const { return m_aborted.load(); } +/*! + * \brief Aborts the operation. + * \remarks The operation will not be killed forcefully. It will be aborted at the next point where it makes sense or even + * finish if it makes no sense to abort. + */ inline void AbortableProgressFeedback::tryToAbort() { return m_aborted.store(true); } +/*! + * \brief Throws an OperationAbortedException if aborted. + * \remarks Supposed to be called only by the operation itself. + */ inline void AbortableProgressFeedback::stopIfAborted() const { if (isAborted()) { @@ -174,6 +248,10 @@ inline void AbortableProgressFeedback::stopIfAborted() const } } +/*! + * \brief Throws an OperationAbortedException if aborted; otherwise the data for the next step is set. + * \remarks Supposed to be called only by the operation itself. + */ inline void AbortableProgressFeedback::nextStepOrStop(const std::string &status, byte percentage) { if (isAborted()) { @@ -182,6 +260,10 @@ inline void AbortableProgressFeedback::nextStepOrStop(const std::string &status, updateStep(status, percentage); } +/*! + * \brief Throws an OperationAbortedException if aborted; otherwise the data for the next step is set. + * \remarks Supposed to be called only by the operation itself. + */ inline void AbortableProgressFeedback::nextStepOrStop(std::string &&status, byte percentage) { if (isAborted()) {