Merge branch 'history-command' into 'main'

Add history undo, redo, and rollback features

See merge request apt-team/apt!518

2 files changed, 51 insertions, 11 deletions

diff --git a/apt-pkg/history.cc b/apt-pkg/history.cc
index 4e838a016..dc48c5464 100644
--- a/apt-pkg/history.cc
+++ b/apt-pkg/history.cc
@@ -16,6 +16,7 @@
 #include <apt-pkg/tagfile.h>
 
 #include <algorithm>
+#include <cassert>
 #include <cctype>
 
 #include <glob.h>
diff --git a/apt-pkg/history.h b/apt-pkg/history.h
index 08e7be388..899d59b24 100644
--- a/apt-pkg/history.h
+++ b/apt-pkg/history.h
@@ -20,38 +20,58 @@
 namespace APT::History
 {
 
+/**
+ * @enum class Kind
+ * @brief Represents the possible actions of APT transactions in history.
+ */
 enum class Kind
 {
    Install,
    Reinstall,
    Upgrade,
    Downgrade,
+   InstallEnd = Downgrade,
    Remove,
    Purge,
 };
 
-// KindToString - Take a kind and return its
-// string representation.
-//
-// NOTE: Non-localized English version
+/**
+ * Get the string parsing specific string representation 
+ * of a @ref Kind.
+ *
+ * @param kind An action kind.
+ * @return A string representation.
+ *
+ * @note This string representation is not localized.
+ */
 std::string KindToString(const Kind &kind);
 
+/**
+ * @struct Change
+ * @brief Represents a package change.
+ */
 struct Change
 {
    Kind kind;
    std::string package;
    std::string currentVersion;
    std::string candidateVersion;
-   bool automatic = false;
+   bool automatic = false; ///< If the change was automatically performed.
 
    private:
    void *d; // pointer for future extension;
 };
 
+static inline bool IsRemoval(const Kind &kind) { return kind > Kind::InstallEnd; }
+
+/**
+ * @struct Entry
+ * @brief Represents an entry in the APT history log.
+ */
 struct Entry
 {
    // Strings instead of string_view to avoid reference errors
-   std::string startDate;
+   std::string startDate;  
    std::string endDate;
    std::string cmdLine;
    std::string comment;
@@ -66,15 +86,34 @@ struct Entry
 // History is defined as the collection of entries in the history log(s).
 typedef std::vector<Entry> HistoryBuffer;
 
-// ParseSection - Take a tag section and parse it as a
-// history log entry.
+/**
+ * Parse a tag section as history log entry.
+ *
+ * @param section A tag section.
+ * @return A history log entry.
+ */
 APT_PUBLIC Entry ParseSection(const pkgTagSection &section);
-// ParseFile - Take a file descriptor and parse it as a history
-// log to the given buffer.
-// NOTE: Caller is responsible for closing the file descriptor.
+
+/**
+ * Parse a file descriptor to a history buffer.
+ *
+ * @param fd A file descriptor.
+ * @param buf A history buffer.
+ * @return true if successful, false otherwise.
+ *
+ * @note Caller is responsible for closing the file descriptor.
+ */
 APT_PUBLIC bool ParseFile(FileFd &fd, HistoryBuffer &buf);
+
 // ParseLogDir - Parse the apt history log directory to the buffer.
+/**
+ * Parse the APT history log directory to a buffer.
+ *
+ * @param buf A history buffer.
+ * @return true if successful, false otherwise.
+ */
 APT_PUBLIC bool ParseLogDir(HistoryBuffer &buf);
+
 } // namespace APT::History
 
 #endif