rpm: TransactionCallbacks class documentation

Add missing documentation to rpm transaction callbacks.

include/libdnf5/rpm/transaction_callbacks.hpp

@@ -39,8 +39,20 @@ namespace libdnf5::rpm {
 using TransactionItem = base::TransactionPackage;
 
 
-/// Base class for Transaction callbacks
+/// The base class for Transaction callbacks.
 /// User implements Transaction callbacks by inheriting this class and overriding its methods.
+///
+/// Typical order in which the transaction callbacks are called is:
+///
+/// -# before_begin
+/// -# verification phase: verify_start, verify_progress, verify_stop
+/// -# script_start, script_stop, script_error for pre transaction scriplets
+/// -# preparation phase: transaction_start, transaction_progress, transaction_stop
+/// -# install packages: elem_progress, install_start, install_progress, install_stop, with their scriptlets
+/// -# remove packages: elem_progress, uninstall_start, uninstall_progress, uninstall_stop, with their scriptlets
+/// -# script_start, script_stop, script_error for post transaction scriplets
+/// -# after_complete
+///
 class LIBDNF_API TransactionCallbacks {
 public:
     /// Scriptlet type
@@ -74,27 +86,92 @@ class LIBDNF_API TransactionCallbacks {
     /// Called right before the rpm transaction is run
     /// @param total Number of elements in the rpm transaction
     virtual void before_begin(uint64_t total);
+
     /// Called after the transaction run finished
     /// @param success Whether the rpm transaction was completed successfully
     virtual void after_complete(bool success);
 
+    /// Report the package installation progress periodically.
+    /// @param item The TransactionPackage class instance for the package currently being installed
+    /// @param amount The portion of the package already installed
+    /// @param total The disk space used by the package after installation
     virtual void install_progress(const TransactionItem & item, uint64_t amount, uint64_t total);
+    /// Installation of a package has started
+    /// @param item The TransactionPackage class instance for the package currently being installed
+    /// @param total The disk space used by the package after installation
     virtual void install_start(const TransactionItem & item, uint64_t total);
+    /// Installation of a package finished
+    /// @param item The TransactionPackage class instance for the package currently being installed
+    /// @param amount The portion of the package that has been installed
+    /// @param total The disk space used by the package after installation
     virtual void install_stop(const TransactionItem & item, uint64_t amount, uint64_t total);
+
+    /// Preparation of a package has started.
+    /// @param amount Index of the package currently being prepared. Items are indexed starting from 0.
+    /// @param total The total number of packages in the transaction
     virtual void transaction_progress(uint64_t amount, uint64_t total);
+    /// Preparation phase has started.
+    /// @param total The total number of packages in the transaction
     virtual void transaction_start(uint64_t total);
+    /// Preparation phase finished.
+    /// @param total The total number of packages in the transaction
     virtual void transaction_stop(uint64_t total);
+
+    /// Report the package removal progress periodically.
+    /// @param item The TransactionPackage class instance for the package currently being removed
+    /// @param amount The portion of the package already uninstalled
+    /// @param total The disk space freed by the package after removal
     virtual void uninstall_progress(const TransactionItem & item, uint64_t amount, uint64_t total);
+    /// Removal of a package has started
+    /// @param item The TransactionPackage class instance for the package currently being removed
+    /// @param total The disk space freed by the package after removal
     virtual void uninstall_start(const TransactionItem & item, uint64_t total);
+    /// Removal of a package finished
+    /// @param item The TransactionPackage class instance for the package currently being removed
+    /// @param amount The portion of the package already uninstalled
+    /// @param total The disk space freed by the package after removal
     virtual void uninstall_stop(const TransactionItem & item, uint64_t amount, uint64_t total);
+
+    /// Unpacking of the package failed.
+    /// @param item The TransactionPackage class instance representing the package that failed to unpack
     virtual void unpack_error(const TransactionItem & item);
+
+    /// cpio error during the package installation. Currentl not used by librpm.
+    /// @param item The TransactionPackage class instance representing the package that caused the error
     virtual void cpio_error(const TransactionItem & item);
+
+    /// Execution of the rpm scriptlet finished with error
+    /// @param item The TransactionPackage class instance for the package that triggered the scriptlet execution.
+    /// @param nevra Nevra of the package that triggered scriptlet execution
+    /// @param type Type of the scriptlet
+    /// @param return_code The return code of the scriptlet execution
     virtual void script_error(const TransactionItem * item, Nevra nevra, ScriptType type, uint64_t return_code);
+    /// Execution of the rpm scriptlet has started
+    /// @param item The TransactionPackage class instance for the package that triggered the scriptlet execution. It can be `nullptr` if the package is not part of the transaction (e.g., a package installation triggered an update of the mandb and man-db was already installed).
+    /// @param nevra Nevra of the package that triggered scriptlet execution
+    /// @param type Type of the scriptlet
     virtual void script_start(const TransactionItem * item, Nevra nevra, ScriptType type);
+    /// Execution of the rpm scriptlet finished without critical error
+    /// @param item The TransactionPackage class instance for the package that triggered the scriptlet execution.
+    /// @param nevra Nevra of the package that triggered scriptlet execution
+    /// @param type Type of the scriptlet
+    /// @param return_code The return code of the scriptlet execution
     virtual void script_stop(const TransactionItem * item, Nevra nevra, ScriptType type, uint64_t return_code);
+
+    /// The installation/removal process for the item has started
+    /// @param amount Index of the package currently being processed. Items are indexed starting from 0.
+    /// @param total The total number of packages in the transaction
     virtual void elem_progress(const TransactionItem & item, uint64_t amount, uint64_t total);
+
+    /// Verification of a package files has started.
+    /// @param amount Index of the package currently being verified. Items are indexed starting from 0.
+    /// @param total The total number of packages to verify
     virtual void verify_progress(uint64_t amount, uint64_t total);
+    /// Packages files verification phase has started. In this phase the signature of packages are verified.
+    /// @param total The total number of packages to verify
     virtual void verify_start(uint64_t total);
+    /// Packages files verification phase finished.
+    /// @param total The total number of packages to verify
     virtual void verify_stop(uint64_t total);
 };