[pacman-dev] [PATCH 07/23] doc: document callbacks

[morganamilo]

---
 lib/libalpm/alpm.h | 439 -
 1 file changed, 271 insertions(+), 168 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index ea99a8b3..a8d48432 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -617,105 +617,12 @@ void alpm_conflict_free(alpm_conflict_t *conflict);
 /* End of alpm_depends */
 /** @} */
 
-/*
- * Enumerations
- * These ones are used in multiple contexts, so are forward-declared.
- */
-
-/** Package install reasons. */
-typedef enum _alpm_pkgreason_t {
-   /** Explicitly requested by the user. */
-   ALPM_PKG_REASON_EXPLICIT = 0,
-   /** Installed as a dependency for another package. */
-   ALPM_PKG_REASON_DEPEND = 1
-} alpm_pkgreason_t;
-
-/** Location a package object was loaded from. */
-typedef enum _alpm_pkgfrom_t {
-   ALPM_PKG_FROM_FILE = 1,
-   ALPM_PKG_FROM_LOCALDB,
-   ALPM_PKG_FROM_SYNCDB
-} alpm_pkgfrom_t;
-
-/** Method used to validate a package. */
-typedef enum _alpm_pkgvalidation_t {
-   ALPM_PKG_VALIDATION_UNKNOWN = 0,
-   ALPM_PKG_VALIDATION_NONE = (1 << 0),
-   ALPM_PKG_VALIDATION_MD5SUM = (1 << 1),
-   ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2),
-   ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3)
-} alpm_pkgvalidation_t;
-
-/*
- * Structures
- */
-
-/** Package group */
-typedef struct _alpm_group_t {
-   /** group name */
-   char *name;
-   /** list of alpm_pkg_t packages */
-   alpm_list_t *packages;
-} alpm_group_t;
 
-/** File in a package */
-typedef struct _alpm_file_t {
-   char *name;
-   off_t size;
-   mode_t mode;
-} alpm_file_t;
-
-/** Package filelist container */
-typedef struct _alpm_filelist_t {
-   size_t count;
-   alpm_file_t *files;
-} alpm_filelist_t;
-
-/** Local package or package file backup entry */
-typedef struct _alpm_backup_t {
-   char *name;
-   char *hash;
-} alpm_backup_t;
-
-/*
- * Hooks
- */
-
-typedef enum _alpm_hook_when_t {
-   ALPM_HOOK_PRE_TRANSACTION = 1,
-   ALPM_HOOK_POST_TRANSACTION
-} alpm_hook_when_t;
-
-/*
- * Logging facilities
- */
-
-/** \addtogroup alpm_log Logging Functions
- * @brief Functions to log using libalpm
+/** \addtogroup alpm_cb Callbacks
+ * @brief Functions and structures for libalpm's callbacks
  * @{
  */
 
-/** Logging Levels */
-typedef enum _alpm_loglevel_t {
-   ALPM_LOG_ERROR= 1,
-   ALPM_LOG_WARNING  = (1 << 1),
-   ALPM_LOG_DEBUG= (1 << 2),
-   ALPM_LOG_FUNCTION = (1 << 3)
-} alpm_loglevel_t;
-
-typedef void (*alpm_cb_log)(alpm_loglevel_t, const char *, va_list);
-
-/** A printf-like function for logging.
- * @param handle the context handle
- * @param prefix caller-specific prefix for the log
- * @param fmt output format
- * @return 0 on success, -1 on error (pm_errno is set accordingly)
- */
-int alpm_logaction(alpm_handle_t *handle, const char *prefix,
-   const char *fmt, ...) __attribute__((format(printf, 3, 4)));
-
-/** @} */
-
 /**
  * Type of events.
  */
@@ -790,7 +697,7 @@ typedef enum _alpm_event_type_t {
/** A .pacnew file was created; See alpm_event_pacnew_created_t for 
arguments. */
ALPM_EVENT_PACNEW_CREATED,
/** A .pacsave file was created; See alpm_event_pacsave_created_t for
-* arguments */
+* arguments. */
ALPM_EVENT_PACSAVE_CREATED,
/** Processing hooks will be started. */
ALPM_EVENT_HOOK_START,
@@ -798,100 +705,123 @@ typedef enum _alpm_event_type_t {
ALPM_EVENT_HOOK_DONE,
/** A hook is starting */
ALPM_EVENT_HOOK_RUN_START,
-   /** A hook has finished running */
+   /** A hook has finished running. */
ALPM_EVENT_HOOK_RUN_DONE
 } alpm_event_type_t;
 
+/** An event that may reprisent any event. */
 typedef struct _alpm_event_any_t {
-   /** Type of event. */
+   /** Type of event */
alpm_event_type_t type;
 } alpm_event_any_t;
 
+/** An enum over the kind of package operations. */
 typedef enum _alpm_package_operation_t {
/** Package (to be) installed. (No oldpkg) */
ALPM_PACKAGE_INSTALL = 1,
/** Package (to be) upgraded */
ALPM_PACKAGE_UPGRADE,
-   /** Package (to be) re-installed. */
+   /** Package (to be) re-installed */
ALPM_PACKAGE_REINSTALL,
-   /** Package (to be) downgraded. */
+   /** Package (to be) downgraded */
ALPM_PACKAGE_DOWNGRADE,
-   /** Package (to be) removed. (No newpkg) */
+   /** Package (to be) removed (No newpkg) */
ALPM_PACKAGE_REMOVE
 } alpm_package_operation_t;
 
+/** A package operation event occurred. */
 typedef struct _alpm_event_package_operation_t {
-   /** Type of event. */
+   /** Type of event */
alpm_event_type_t type;
-   /** Type of operation. */
+   /** Type of operation */
alpm_package_operation_t operation;
-   /** Old package. */
+   /** Old package */
alpm_pkg_t *oldpkg;
-   /** New 

[pacman-dev] [PATCH 08/23] doc: document databases

[morganamilo]

---
 lib/libalpm/alpm.h | 468 -
 1 file changed, 249 insertions(+), 219 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index a8d48432..c71c275f 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -94,6 +94,38 @@ typedef struct __alpm_pkg_t alpm_pkg_t;
 /** Transaction structure used internally by libalpm */
 typedef struct __alpm_trans_t alpm_trans_t;
 
+/*
+ * Structures
+ */
+
+/** Package group */
+typedef struct _alpm_group_t {
+   /** group name */
+   char *name;
+   /** list of alpm_pkg_t packages */
+   alpm_list_t *packages;
+} alpm_group_t;
+
+/** File in a package */
+typedef struct _alpm_file_t {
+   char *name;
+   off_t size;
+   mode_t mode;
+} alpm_file_t;
+
+/** Package filelist container */
+typedef struct _alpm_filelist_t {
+   size_t count;
+   alpm_file_t *files;
+} alpm_filelist_t;
+
+/** Local package or package file backup entry */
+typedef struct _alpm_backup_t {
+   char *name;
+   char *hash;
+} alpm_backup_t;
+
+
 
 /** @addtogroup alpm_api ALPM
  * @brief The libalpm Public API
@@ -1123,6 +1155,223 @@ typedef int (*alpm_cb_fetch)(const char *url, const 
char *localpath,
 /** @} */
 
 
+/** @addtogroup alpm_databases Database
+ * @brief Functions to query and manipulate the database of libalpm.
+ * @{
+ */
+
+/** Get the database of locally installed packages.
+ * The returned pointer points to an internal structure
+ * of libalpm which should only be manipulated through
+ * libalpm functions.
+ * @return a reference to the local database
+ */
+alpm_db_t *alpm_get_localdb(alpm_handle_t *handle);
+
+/** Get the list of sync databases.
+ * Returns a list of alpm_db_t structures, one for each registered
+ * sync database.
+ *
+ * @param handle the context handle
+ * @return a reference to an internal list of alpm_db_t structures
+ */
+alpm_list_t *alpm_get_syncdbs(alpm_handle_t *handle);
+
+/** Register a sync database of packages.
+ * Databases can not be registered when there is an active transaction.
+ *
+ * @param handle the context handle
+ * @param treename the name of the sync repository
+ * @param level what level of signature checking to perform on the
+ * database; note that this must be a '.sig' file type verification
+ * @return an alpm_db_t* on success (the value), NULL on error
+ */
+alpm_db_t *alpm_register_syncdb(alpm_handle_t *handle, const char *treename,
+   int level);
+
+/** Unregister all package databases.
+ * Databases can not be unregistered while there is an active transaction.
+ *
+ * @param handle the context handle
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
+int alpm_unregister_all_syncdbs(alpm_handle_t *handle);
+
+/** Unregister a package database.
+ * Databases can not be unregistered when there is an active transaction.
+ *
+ * @param db pointer to the package database to unregister
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
+int alpm_db_unregister(alpm_db_t *db);
+
+/** Get the name of a package database.
+ * @param db pointer to the package database
+ * @return the name of the package database, NULL on error
+ */
+const char *alpm_db_get_name(const alpm_db_t *db);
+
+/** Get the signature verification level for a database.
+ * Will return the default verification level if this database is set up
+ * with ALPM_SIG_USE_DEFAULT.
+ * @param db pointer to the package database
+ * @return the signature verification level
+ */
+int alpm_db_get_siglevel(alpm_db_t *db);
+
+/** Check the validity of a database.
+ * This is most useful for sync databases and verifying signature status.
+ * If invalid, the handle error code will be set accordingly.
+ * @param db pointer to the package database
+ * @return 0 if valid, -1 if invalid (pm_errno is set accordingly)
+ */
+int alpm_db_get_valid(alpm_db_t *db);
+
+/** @name Server accessors
+ * @{
+ */
+
+/** Get the list of servers assigned to this db.
+ * @param db pointer to the database to get the servers from
+ * @return a char* list of servers
+ */
+alpm_list_t *alpm_db_get_servers(const alpm_db_t *db);
+
+/** Sets the list of servers for the database to use.
+ * @param db the database to set the servers
+ * @param servers a char* list of servers. Note: the database will
+ * take ownership of the list and it should no longer be
+ * freed by the caller
+ */
+int alpm_db_set_servers(alpm_db_t *db, alpm_list_t *servers);
+
+/** Add a download server to a database.
+ * @param db database pointer
+ * @param url url of the server
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
+int alpm_db_add_server(alpm_db_t *db, const char *url);
+
+/** Remove a download server from a database.
+ * @param db database pointer
+ * @param url url of the server
+ * @return 0 on success, 1 on server not present,
+ * -1 on error (pm_errno is set accordingly)
+ */
+int alpm_db_remove_server(alpm_db_t *db, const char *url);
+

Re: [pacman-dev] [PATCH 00/23] Docs Docs Docs 2: electric boogaloo

[Morgan Adamiec]

On 07/12/2020 22:59, Colin Woodbury wrote:
> I enjoy writing docs, is there anywhere you'd like a hand? 
> 
> On Mon, 7 Dec 2020, at 14:19, morganamilo wrote:
>> Here's a redo of my original docs patch and more.
>>
>> This time it's split in to many commits so it's hopefully easier to
>> review/rebase.
>>
>> Every function, struct and param is now documented.
>>
>> Simply `man libalpm` to get the main page. Then `man libalpm-databases`
>> to see the database section and so on for each section.
>>
>> Also while doing all this, I thought it would make sense to change some
>> function names:
>>
>> I also think alpm_unlock() should be named alpm_db_unlock() and
>> alpm_sync_get_new_version() should be named alpm_pkg_get_new_version()
>>
>> Then the functions could be moved into the db and packages groups
>> repectivley.
>>
>> To be clear I have not actually changed any function names in this patch
>> set.
>>
>> morganamilo (23):
>>   doc: remove stray doxygen comment
>>   doc: add doc header to alpm.h
>>   doc: document error
>>   doc: document handle
>>   doc: document signatures
>>   doc: document depends
>>   doc: document callbacks
>>   doc: document databases
>>   doc: document logging
>>   doc: document packages
>>   doc: document files and groups
>>   doc: document transactions
>>   doc: document misc
>>   doc: document alpm_list
>>   doc: document options
>>   doc: move alpm_api group to top of file
>>   doc: move top level items into groups
>>   doc: configure doxygen
>>   doc: update doxyfile
>>   doc: rename alpm_api group to alpm
>>   doc: add extra documentation to the man page
>>   doc: change group names to libalpm_*
>>   doc: remove old libalpm man file
>>
>> doc/Doxyfile.in |   83 +-
>> doc/libalpm.3.asciidoc  |   37 -
>> doc/meson.build |1 -
>> lib/libalpm/alpm.h  | 2429 +++
>> lib/libalpm/alpm_list.c |  251 
>> lib/libalpm/alpm_list.h |  293 -
>> lib/libalpm/trans.c |2 -
>> 7 files changed, 2048 insertions(+), 1048 deletions(-)
>> delete mode 100644 doc/libalpm.3.asciidoc
>>
>> -- 
>> 2.29.2
>>

You're a little late now ;)

I guess go review it for me :P

[pacman-dev] [PATCH 12/23] doc: document transactions

[morganamilo]

---
 lib/libalpm/alpm.h | 35 +++
 1 file changed, 23 insertions(+), 12 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 30bfb06d..76ae5722 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -2068,18 +2068,26 @@ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct 
archive *archive);
 /* End of alpm_packages */
 /** @} */
 
-
-/*
- * Sync
- */
-
 /** Check for new version of pkg in sync repos
  * (only the first occurrence is considered in sync)
  */
 alpm_pkg_t *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync);
 
-/** @addtogroup alpm_api_trans Transaction Functions
- * Functions to manipulate libalpm transactions
+/** @addtogroup alpm_trans Transaction
+ * @brief Functions to manipulate libalpm transactions
+ *
+ * Transactions are the way to add/remove packages to/from the system.
+ * Only one transaction can exist at a time.
+ *
+ * The basic workflow of a transaction is to:
+ *
+ * - Initialize with \link alpm_trans_init \endlink
+ * - Choose which packages to add with \link alpm_add_pkg \endlink and \link 
alpm_remove_pkg \endlink
+ * - Prepare the transaction with \link alpm_trans_prepare \endlink
+ * - Commit the transaction with \link alpm_trans_commit \endlink
+ * - Release the transaction with \link alpm_trans_release \endlink
+ *
+ * A transaction can be released at any time. A transaction does not have to 
be committed.
  * @{
  */
 
@@ -2172,10 +2180,11 @@ int alpm_trans_interrupt(alpm_handle_t *handle);
  * @return 0 on success, -1 on error (pm_errno is set accordingly)
  */
 int alpm_trans_release(alpm_handle_t *handle);
-/** @} */
 
-/** @name Common Transactions */
-/** @{ */
+/** @name Add/Remove packages
+ * These functions remove/add packages to the transactions
+ * @{
+ * */
 
 /** Search for packages to upgrade and add them to the transaction.
  * @param handle the context handle
@@ -2186,22 +2195,24 @@ int alpm_sync_sysupgrade(alpm_handle_t *handle, int 
enable_downgrade);
 
 /** Add a package to the transaction.
  * If the package was loaded by alpm_pkg_load(), it will be freed upon
- * alpm_trans_release() invocation.
+ * \link alpm_trans_release \endlink invocation.
  * @param handle the context handle
  * @param pkg the package to add
  * @return 0 on success, -1 on error (pm_errno is set accordingly)
  */
 int alpm_add_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg);
 
-/** Add a package removal action to the transaction.
+/** Add a package removal to the transaction.
  * @param handle the context handle
  * @param pkg the package to uninstall
  * @return 0 on success, -1 on error (pm_errno is set accordingly)
  */
 int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg);
 
+/* End of add/remove packages */
 /** @} */
 
+/* End of alpm_trans */
 /** @} */
 
 /*
-- 
2.29.2

[pacman-dev] [PATCH 15/23] doc: document options

[morganamilo]

---
 lib/libalpm/alpm.h | 592 ++---
 1 file changed, 564 insertions(+), 28 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 494a8319..05dec6c7 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -1453,186 +1453,722 @@ int alpm_logaction(alpm_handle_t *handle, const char 
*prefix,
 /** @} */
 
 
-/** @addtogroup alpm_api_options Options
+/** @addtogroup alpm_options Options
  * Libalpm option getters and setters
  * @{
  */
 
-/** Returns the callback used for logging. */
+/** @name Accessors for callbacks
+ * @{
+ */
+
+/** Returns the callback used for logging.
+ * @param handle the context handle
+ * @return the currently set log callback
+ */
 alpm_cb_log alpm_option_get_logcb(alpm_handle_t *handle);
-/** Sets the callback used for logging. */
+
+/** Sets the callback used for logging. 
+ * @param handle the context handle
+ * @param cb the cb to use
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_logcb(alpm_handle_t *handle, alpm_cb_log cb);
 
-/** Returns the callback used to report download progress. */
+/** Returns the callback used to report download progress. 
+ * @param handle the context handle
+ * @return the currently set download callback
+ */
 alpm_cb_download alpm_option_get_dlcb(alpm_handle_t *handle);
-/** Sets the callback used to report download progress. */
+
+/** Sets the callback used to report download progress.
+ * @param handle the context handle
+ * @param cb the cb to use
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_dlcb(alpm_handle_t *handle, alpm_cb_download cb);
 
-/** Returns the downloading callback. */
+/** Returns the downloading callback.
+ * @param handle the context handle
+ * @return the currently set fetch callback
+ */
 alpm_cb_fetch alpm_option_get_fetchcb(alpm_handle_t *handle);
-/** Sets the downloading callback. */
+
+/** Sets the downloading callback.
+ * @param handle the context handle
+ * @param cb the cb to use
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_fetchcb(alpm_handle_t *handle, alpm_cb_fetch cb);
 
-/** Returns the callback used to report total download size. */
+/** Returns the callback used to report total download size. 
+ * @param handle the context handle
+ * @return the currently set total download callback
+ */
 alpm_cb_totaldl alpm_option_get_totaldlcb(alpm_handle_t *handle);
-/** Sets the callback used to report total download size. */
+
+/** Sets the callback used to report total download size.
+ * @param handle the context handle
+ * @param cb the cb to use
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_totaldlcb(alpm_handle_t *handle, alpm_cb_totaldl cb);
 
-/** Returns the callback used for events. */
+
+/** Returns the callback used for events.
+ * @param handle the context handle
+ * @return the currently set event callback
+ */
 alpm_cb_event alpm_option_get_eventcb(alpm_handle_t *handle);
-/** Sets the callback used for events. */
+
+/** Sets the callback used for events.
+ * @param handle the context handle
+ * @param cb the cb to use
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_eventcb(alpm_handle_t *handle, alpm_cb_event cb);
 
-/** Returns the callback used for questions. */
+/** Returns the callback used for questions.
+ * @param handle the context handle
+ * @return the currently set question callback
+ */
 alpm_cb_question alpm_option_get_questioncb(alpm_handle_t *handle);
-/** Sets the callback used for questions. */
+
+/** Sets the callback used for questions.
+ * @param handle the context handle
+ * @param cb the cb to use
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_questioncb(alpm_handle_t *handle, alpm_cb_question cb);
 
-/** Returns the callback used for operation progress. */
+
+/**Returns the callback used for operation progress.
+ * @param handle the context handle
+ * @return the currently set progress callback
+ */
 alpm_cb_progress alpm_option_get_progresscb(alpm_handle_t *handle);
-/** Sets the callback used for operation progress. */
+
+/** Sets the callback used for operation progress.
+ * @param handle the context handle
+ * @param cb the cb to use
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_progresscb(alpm_handle_t *handle, alpm_cb_progress cb);
+/* End of callback accessors */
+/** @} */
+
+
+/** @name Accessors to the root directory
+ *
+ * The root directory is the prefix to which libalpm installs packages to.
+ * Hooks and scriptlets will also be run in a chroot to ensure they behave 
correctly
+ * in alternative roots.
+ * @{
+ */
 
-/** Returns the root of the destination filesystem. Read-only. */
+/** Returns the root path. Read-only.
+ * @param handle the context handle
+ */
 const char 

[pacman-dev] [PATCH 06/23] doc: document depends

[morganamilo]

---
 lib/libalpm/alpm.h | 295 +
 1 file changed, 164 insertions(+), 131 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 43a47d54..ea99a8b3 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -441,49 +441,26 @@ int alpm_extract_keyid(alpm_handle_t *handle, const char 
*identifier,
 /** @} */
 
 
-/*
- * Enumerations
- * These ones are used in multiple contexts, so are forward-declared.
+/** @addtogroup alpm_depends Dependency
+ * @brief Functions dealing with libalpm's dependency and conflict
+ * information.
+ * @{
  */
 
-/** Package install reasons. */
-typedef enum _alpm_pkgreason_t {
-   /** Explicitly requested by the user. */
-   ALPM_PKG_REASON_EXPLICIT = 0,
-   /** Installed as a dependency for another package. */
-   ALPM_PKG_REASON_DEPEND = 1
-} alpm_pkgreason_t;
-
-/** Location a package object was loaded from. */
-typedef enum _alpm_pkgfrom_t {
-   ALPM_PKG_FROM_FILE = 1,
-   ALPM_PKG_FROM_LOCALDB,
-   ALPM_PKG_FROM_SYNCDB
-} alpm_pkgfrom_t;
-
-/** Method used to validate a package. */
-typedef enum _alpm_pkgvalidation_t {
-   ALPM_PKG_VALIDATION_UNKNOWN = 0,
-   ALPM_PKG_VALIDATION_NONE = (1 << 0),
-   ALPM_PKG_VALIDATION_MD5SUM = (1 << 1),
-   ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2),
-   ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3)
-} alpm_pkgvalidation_t;
-
 /** Types of version constraints in dependency specs. */
 typedef enum _alpm_depmod_t {
-   /** No version constraint */
-   ALPM_DEP_MOD_ANY = 1,
-   /** Test version equality (package=x.y.z) */
-   ALPM_DEP_MOD_EQ,
-   /** Test for at least a version (package>=x.y.z) */
-   ALPM_DEP_MOD_GE,
-   /** Test for at most a version (package<=x.y.z) */
-   ALPM_DEP_MOD_LE,
-   /** Test for greater than some version (package>x.y.z) */
-   ALPM_DEP_MOD_GT,
-   /** Test for less than some version (package=x.y.z) */
+ALPM_DEP_MOD_GE,
+/** Test for at most a version (package<=x.y.z) */
+ALPM_DEP_MOD_LE,
+/** Test for greater than some version (package>x.y.z) */
+ALPM_DEP_MOD_GT,
+/** Test for less than some version (package=2.12"
+ */
+char *alpm_dep_compute_string(const alpm_depend_t *dep);
+
+/** Return a newly allocated dependency information parsed from a string
+ *\link alpm_dep_free should be used to free the dependency \endlink
+ * @param depstring a formatted string, e.g. "glibc=2.12"
+ * @return a dependency info structure
+ */
+alpm_depend_t *alpm_dep_from_string(const char *depstring);
+
+/** Free a dependency info structure
+ * @param dep struct to free
+ */
+void alpm_dep_free(alpm_depend_t *dep);
+
+/** Free a fileconflict and its members.
+ * @param conflict the fileconflict to free
+ */
+void alpm_fileconflict_free(alpm_fileconflict_t *conflict);
+
+/** Free a depmissing and its members
+ * @param miss the depmissing to fre 
+ * */
+void alpm_depmissing_free(alpm_depmissing_t *miss);
+
+/**
+ * Free a conflict and its members.
+ * @param conflict the conflict to free
+ */
+void alpm_conflict_free(alpm_conflict_t *conflict);
+
+
+/* End of alpm_depends */
+/** @} */
+
+/*
+ * Enumerations
+ * These ones are used in multiple contexts, so are forward-declared.
+ */
+
+/** Package install reasons. */
+typedef enum _alpm_pkgreason_t {
+   /** Explicitly requested by the user. */
+   ALPM_PKG_REASON_EXPLICIT = 0,
+   /** Installed as a dependency for another package. */
+   ALPM_PKG_REASON_DEPEND = 1
+} alpm_pkgreason_t;
+
+/** Location a package object was loaded from. */
+typedef enum _alpm_pkgfrom_t {
+   ALPM_PKG_FROM_FILE = 1,
+   ALPM_PKG_FROM_LOCALDB,
+   ALPM_PKG_FROM_SYNCDB
+} alpm_pkgfrom_t;
+
+/** Method used to validate a package. */
+typedef enum _alpm_pkgvalidation_t {
+   ALPM_PKG_VALIDATION_UNKNOWN = 0,
+   ALPM_PKG_VALIDATION_NONE = (1 << 0),
+   ALPM_PKG_VALIDATION_MD5SUM = (1 << 1),
+   ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2),
+   ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3)
+} alpm_pkgvalidation_t;
+
+/*
+ * Structures
+ */
+
 /** Package group */
 typedef struct _alpm_group_t {
/** group name */
@@ -1900,76 +2016,6 @@ int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t 
*pkg);
 
 /** @} */
 
-/** @addtogroup alpm_api_depends Dependency Functions
- * Functions dealing with libalpm representation of dependency
- * information.
- * @{
- */
-
-/** Checks dependencies and returns missing ones in a list.
- * Dependencies can include versions with depmod operators.
- * @param handle the context handle
- * @param pkglist the list of local packages
- * @param remove an alpm_list_t* of packages to be removed
- * @param upgrade an alpm_list_t* of packages to be upgraded 
(remove-then-upgrade)
- * @param reversedeps handles the backward dependencies
- * @return an alpm_list_t* of alpm_depmissing_t pointers.
- */
-alpm_list_t *alpm_checkdeps(alpm_handle_t *handle, 

Re: [pacman-dev] [PATCH 00/23] Docs Docs Docs 2: electric boogaloo

[Colin Woodbury]

I enjoy writing docs, is there anywhere you'd like a hand? 

On Mon, 7 Dec 2020, at 14:19, morganamilo wrote:
> Here's a redo of my original docs patch and more.
> 
> This time it's split in to many commits so it's hopefully easier to
> review/rebase.
> 
> Every function, struct and param is now documented.
> 
> Simply `man libalpm` to get the main page. Then `man libalpm-databases`
> to see the database section and so on for each section.
> 
> Also while doing all this, I thought it would make sense to change some
> function names:
> 
> I also think alpm_unlock() should be named alpm_db_unlock() and
> alpm_sync_get_new_version() should be named alpm_pkg_get_new_version()
> 
> Then the functions could be moved into the db and packages groups
> repectivley.
> 
> To be clear I have not actually changed any function names in this patch
> set.
> 
> morganamilo (23):
>   doc: remove stray doxygen comment
>   doc: add doc header to alpm.h
>   doc: document error
>   doc: document handle
>   doc: document signatures
>   doc: document depends
>   doc: document callbacks
>   doc: document databases
>   doc: document logging
>   doc: document packages
>   doc: document files and groups
>   doc: document transactions
>   doc: document misc
>   doc: document alpm_list
>   doc: document options
>   doc: move alpm_api group to top of file
>   doc: move top level items into groups
>   doc: configure doxygen
>   doc: update doxyfile
>   doc: rename alpm_api group to alpm
>   doc: add extra documentation to the man page
>   doc: change group names to libalpm_*
>   doc: remove old libalpm man file
> 
> doc/Doxyfile.in |   83 +-
> doc/libalpm.3.asciidoc  |   37 -
> doc/meson.build |1 -
> lib/libalpm/alpm.h  | 2429 +++
> lib/libalpm/alpm_list.c |  251 
> lib/libalpm/alpm_list.h |  293 -
> lib/libalpm/trans.c |2 -
> 7 files changed, 2048 insertions(+), 1048 deletions(-)
> delete mode 100644 doc/libalpm.3.asciidoc
> 
> -- 
> 2.29.2
> 

[pacman-dev] [PATCH 09/23] doc: document logging

[morganamilo]

---
 lib/libalpm/alpm.h | 25 -
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index c71c275f..ea690abc 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -1412,13 +1412,27 @@ typedef enum _alpm_pkgvalidation_t {
 
 /** Logging Levels */
 typedef enum _alpm_loglevel_t {
-   ALPM_LOG_ERROR= 1,
-   ALPM_LOG_WARNING  = (1 << 1),
-   ALPM_LOG_DEBUG= (1 << 2),
-   ALPM_LOG_FUNCTION = (1 << 3)
+   /** Error */
+   ALPM_LOG_ERROR= 1,
+   /** Warning */
+   ALPM_LOG_WARNING  = (1 << 1),
+   /** Debug */
+   ALPM_LOG_DEBUG= (1 << 2),
+   /** Function */
+   ALPM_LOG_FUNCTION = (1 << 3)
 } alpm_loglevel_t;
 
-typedef void (*alpm_cb_log)(alpm_loglevel_t, const char *, va_list);
+
+/** The callback type for logging.
+ *
+ * libalpm will call this function whenever something is to be logged.
+ * many libalpm will produce log output. Additionally any calls to \link 
alpm_logaction
+ * \endlink will also call this callback.
+ * @param level the currently set loglevel
+ * @param fmt the printf like format string
+ * @param args printf like arguments
+ */
+typedef void (*alpm_cb_log)(alpm_loglevel_t level, const char *fmt, va_list 
args);
 
 /** A printf-like function for logging.
  * @param handle the context handle
@@ -1429,6 +1443,7 @@ typedef void (*alpm_cb_log)(alpm_loglevel_t, const char 
*, va_list);
 int alpm_logaction(alpm_handle_t *handle, const char *prefix,
const char *fmt, ...) __attribute__((format(printf, 3, 4)));
 
+/* End of alpm_log */
 /** @} */
 
 /** Fetch a list of remote packages.
-- 
2.29.2

[pacman-dev] [PATCH 14/23] doc: document alpm_list

[morganamilo]

---
 lib/libalpm/alpm_list.c | 251 -
 lib/libalpm/alpm_list.h | 299 +++-
 2 files changed, 295 insertions(+), 255 deletions(-)

diff --git a/lib/libalpm/alpm_list.c b/lib/libalpm/alpm_list.c
index fe0c2906..2ecc8e0b 100644
--- a/lib/libalpm/alpm_list.c
+++ b/lib/libalpm/alpm_list.c
@@ -32,23 +32,8 @@
 #define SYMEXPORT __attribute__((visibility("default")))
 #define SYMHIDDEN __attribute__((visibility("internal")))
 
-/**
- * @addtogroup alpm_list List Functions
- * @brief Functions to manipulate alpm_list_t lists.
- *
- * These functions are designed to create, destroy, and modify lists of
- * type alpm_list_t. This is an internal list type used by libalpm that is
- * publicly exposed for use by frontends if desired.
- *
- * @{ */
-
 /* Allocation */
 
-/**
- * @brief Free a list, but not the contained data.
- *
- * @param list the list to free
- */
 void SYMEXPORT alpm_list_free(alpm_list_t *list)
 {
alpm_list_t *it = list;
@@ -60,12 +45,6 @@ void SYMEXPORT alpm_list_free(alpm_list_t *list)
}
 }
 
-/**
- * @brief Free the internal data of a list structure.
- *
- * @param list the list to free
- * @param fn   a free function for the internal data
- */
 void SYMEXPORT alpm_list_free_inner(alpm_list_t *list, alpm_list_fn_free fn)
 {
alpm_list_t *it = list;
@@ -83,28 +62,12 @@ void SYMEXPORT alpm_list_free_inner(alpm_list_t *list, 
alpm_list_fn_free fn)
 
 /* Mutators */
 
-/**
- * @brief Add a new item to the end of the list.
- *
- * @param list the list to add to
- * @param data the new item to be added to the list
- *
- * @return the resultant list
- */
 alpm_list_t SYMEXPORT *alpm_list_add(alpm_list_t *list, void *data)
 {
alpm_list_append(, data);
return list;
 }
 
-/**
- * @brief Add a new item to the end of the list.
- *
- * @param list the list to add to
- * @param data the new item to be added to the list
- *
- * @return the newly added item
- */
 alpm_list_t SYMEXPORT *alpm_list_append(alpm_list_t **list, void *data)
 {
alpm_list_t *ptr;
@@ -131,14 +94,6 @@ alpm_list_t SYMEXPORT *alpm_list_append(alpm_list_t **list, 
void *data)
return ptr;
 }
 
-/**
- * @brief Duplicate and append a string to a list.
- *
- * @param list the list to append to
- * @param data the string to duplicate and append
- *
- * @return the newly added item
- */
 alpm_list_t SYMEXPORT *alpm_list_append_strdup(alpm_list_t **list, const char 
*data)
 {
alpm_list_t *ret;
@@ -151,15 +106,6 @@ alpm_list_t SYMEXPORT *alpm_list_append_strdup(alpm_list_t 
**list, const char *d
}
 }
 
-/**
- * @brief Add items to a list in sorted order.
- *
- * @param list the list to add to
- * @param data the new item to be added to the list
- * @param fn   the comparison function to use to determine order
- *
- * @return the resultant list
- */
 alpm_list_t SYMEXPORT *alpm_list_add_sorted(alpm_list_t *list, void *data, 
alpm_list_fn_cmp fn)
 {
if(!fn || !list) {
@@ -202,17 +148,6 @@ alpm_list_t SYMEXPORT *alpm_list_add_sorted(alpm_list_t 
*list, void *data, alpm_
}
 }
 
-/**
- * @brief Join two lists.
- * The two lists must be independent. Do not free the original lists after
- * calling this function, as this is not a copy operation. The list pointers
- * passed in should be considered invalid after calling this function.
- *
- * @param first  the first list
- * @param second the second list
- *
- * @return the resultant joined list
- */
 alpm_list_t SYMEXPORT *alpm_list_join(alpm_list_t *first, alpm_list_t *second)
 {
alpm_list_t *tmp;
@@ -235,15 +170,6 @@ alpm_list_t SYMEXPORT *alpm_list_join(alpm_list_t *first, 
alpm_list_t *second)
return first;
 }
 
-/**
- * @brief Merge the two sorted sublists into one sorted list.
- *
- * @param left  the first list
- * @param right the second list
- * @param fncomparison function for determining merge order
- *
- * @return the resultant list
- */
 alpm_list_t SYMEXPORT *alpm_list_mmerge(alpm_list_t *left, alpm_list_t *right,
alpm_list_fn_cmp fn)
 {
@@ -305,15 +231,6 @@ alpm_list_t SYMEXPORT *alpm_list_mmerge(alpm_list_t *left, 
alpm_list_t *right,
return newlist;
 }
 
-/**
- * @brief Sort a list of size `n` using mergesort algorithm.
- *
- * @param list the list to sort
- * @param nthe size of the list
- * @param fn   the comparison function for determining order
- *
- * @return the resultant list
- */
 alpm_list_t SYMEXPORT *alpm_list_msort(alpm_list_t *list, size_t n,
alpm_list_fn_cmp fn)
 {
@@ -339,15 +256,6 @@ alpm_list_t SYMEXPORT *alpm_list_msort(alpm_list_t *list, 
size_t n,
return list;
 }
 
-/**
- * @brief Remove an item from the list.
- * item is not freed; this is the responsibility of the caller.
- *
- * @param haystack the list to remove the item from
- * @param item the item to remove from the list
- *
- * @return the resultant list
- */
 alpm_list_t SYMEXPORT 

[pacman-dev] [PATCH 19/23] doc: update doxyfile

[morganamilo]

---
 doc/Doxyfile.in | 81 +++--
 1 file changed, 59 insertions(+), 22 deletions(-)

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index e2101a28..776318da 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -1,4 +1,4 @@
-# Doxyfile 1.8.2
+# Doxyfile 1.8.20
 
 #---
 # Project related configuration options
@@ -10,7 +10,9 @@ PROJECT_BRIEF  = "Arch Linux Package Manager Library"
 PROJECT_LOGO   =
 OUTPUT_DIRECTORY   = @OUTPUT_DIRECTORY@
 CREATE_SUBDIRS = NO
+ALLOW_UNICODE_NAMES= NO
 OUTPUT_LANGUAGE= English
+OUTPUT_TEXT_DIRECTION  = None
 BRIEF_MEMBER_DESC  = YES
 REPEAT_BRIEF   = YES
 ABBREVIATE_BRIEF   = "The $name class" \
@@ -31,36 +33,41 @@ STRIP_FROM_PATH=
 STRIP_FROM_INC_PATH=
 SHORT_NAMES= NO
 JAVADOC_AUTOBRIEF  = YES
+JAVADOC_BANNER = NO
 QT_AUTOBRIEF   = NO
 MULTILINE_CPP_IS_BRIEF = NO
+PYTHON_DOCSTRING   = YES
 INHERIT_DOCS   = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE   = 4
 ALIASES=
-TCL_SUBST  =
 OPTIMIZE_OUTPUT_FOR_C  = YES
 OPTIMIZE_OUTPUT_JAVA   = NO
 OPTIMIZE_FOR_FORTRAN   = NO
 OPTIMIZE_OUTPUT_VHDL   = NO
+OPTIMIZE_OUTPUT_SLICE  = NO
 EXTENSION_MAPPING  =
 MARKDOWN_SUPPORT   = YES
+TOC_INCLUDE_HEADINGS   = 5
 AUTOLINK_SUPPORT   = YES
 BUILTIN_STL_SUPPORT= NO
 CPP_CLI_SUPPORT= NO
 SIP_SUPPORT= NO
 IDL_PROPERTY_SUPPORT   = YES
 DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
 SUBGROUPING= YES
 INLINE_GROUPED_CLASSES = NO
-INLINE_SIMPLE_STRUCTS  = NO
+INLINE_SIMPLE_STRUCTS  = YES
 TYPEDEF_HIDES_STRUCT   = YES
-SYMBOL_CACHE_SIZE  = 0
 LOOKUP_CACHE_SIZE  = 0
+NUM_PROC_THREADS   = 1
 #---
 # Build related configuration options
 #---
 EXTRACT_ALL= NO
 EXTRACT_PRIVATE= NO
+EXTRACT_PRIV_VIRTUAL   = NO
 EXTRACT_PACKAGE= NO
 EXTRACT_STATIC = NO
 EXTRACT_LOCAL_CLASSES  = YES
@@ -73,7 +80,9 @@ HIDE_IN_BODY_DOCS  = YES
 INTERNAL_DOCS  = NO
 CASE_SENSE_NAMES   = YES
 HIDE_SCOPE_NAMES   = NO
+HIDE_COMPOUND_REFERENCE= NO
 SHOW_INCLUDE_FILES = YES
+SHOW_GROUPED_MEMB_INC  = NO
 FORCE_LOCAL_INCLUDES   = NO
 INLINE_INFO= YES
 SORT_MEMBER_DOCS   = YES
@@ -95,26 +104,29 @@ FILE_VERSION_FILTER=
 LAYOUT_FILE=
 CITE_BIB_FILES =
 #---
-# configuration options related to warning and progress messages
+# Configuration options related to warning and progress messages
 #---
 QUIET  = NO
 WARNINGS   = YES
 WARN_IF_UNDOCUMENTED   = YES
 WARN_IF_DOC_ERROR  = YES
 WARN_NO_PARAMDOC   = NO
+WARN_AS_ERROR  = NO
 WARN_FORMAT= "$file:$line: $text"
 WARN_LOGFILE   =
 #---
-# configuration options related to the input files
+# Configuration options related to the input files
 #---
-INPUT  = ../lib/libalpm/alpm.h ../lib/libalpm/alpm_list.h
+INPUT  = ../lib/libalpm/alpm.h \
+ ../lib/libalpm/alpm_list.h
 INPUT_ENCODING = UTF-8
 FILE_PATTERNS  =
 RECURSIVE  = NO
 EXCLUDE=
 EXCLUDE_SYMLINKS   = NO
 EXCLUDE_PATTERNS   =
-EXCLUDE_SYMBOLS= _alpm_* __alpm_*
+EXCLUDE_SYMBOLS= _alpm_* \
+ __alpm_*
 EXAMPLE_PATH   =
 EXAMPLE_PATTERNS   = *
 EXAMPLE_RECURSIVE  = NO
@@ -123,8 +135,9 @@ INPUT_FILTER   =
 FILTER_PATTERNS=
 FILTER_SOURCE_FILES= NO
 FILTER_SOURCE_PATTERNS =
+USE_MDFILE_AS_MAINPAGE =
 #---
-# configuration options related to source browsing
+# Configuration options related to source browsing
 #---
 SOURCE_BROWSER = NO
 INLINE_SOURCES = NO
@@ -132,16 +145,17 @@ STRIP_CODE_COMMENTS= NO
 REFERENCED_BY_RELATION = YES
 REFERENCES_RELATION= YES
 REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS= YES
 USE_HTAGS  = NO
 VERBATIM_HEADERS   = YES
 #---
-# configuration options related to the alphabetical class index
+# Configuration options related to the alphabetical class index
 #---
 ALPHABETICAL_INDEX = NO
 

[pacman-dev] [PATCH 05/23] doc: document signatures

[morganamilo]

---
 lib/libalpm/alpm.h | 282 +++--
 1 file changed, 167 insertions(+), 115 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 178c8f6a..43a47d54 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -265,7 +265,7 @@ alpm_handle_t *alpm_initialize(const char *root, const char 
*dbpath,
  * This should be the last alpm call you make.
  * After this returns, handle should be considered invalid and cannot be reused
  * in any way.
- * @param myhandle the context handle
+ * @param handle the context handle
  * @return 0 on success, -1 on error
  */
 int alpm_release(alpm_handle_t *handle);
@@ -275,6 +275,172 @@ int alpm_release(alpm_handle_t *handle);
 
 typedef int64_t alpm_time_t;
 
+/** @addtogroup alpm_sig Signature checking
+ * @brief Functions to check signatures
+ * @{
+ */
+
+/** PGP signature verification options */
+typedef enum _alpm_siglevel_t {
+   /** Packages require a signature */
+   ALPM_SIG_PACKAGE = (1 << 0),
+   /** Packages do not require a signature,
+* but check packages that do have signatures */
+   ALPM_SIG_PACKAGE_OPTIONAL = (1 << 1),
+   /* Allow packages with signatures that are marginal trust */
+   ALPM_SIG_PACKAGE_MARGINAL_OK = (1 << 2),
+   /** Allow packages with signatues that are unknown trust */
+   ALPM_SIG_PACKAGE_UNKNOWN_OK = (1 << 3),
+
+   /** Databases require a signature */
+   ALPM_SIG_DATABASE = (1 << 10),
+   /** Databases do not require a signature,
+* but check databases that do have signatures */
+   ALPM_SIG_DATABASE_OPTIONAL = (1 << 11),
+   /** Allow databases with signatures that are marginal trust */
+   ALPM_SIG_DATABASE_MARGINAL_OK = (1 << 12),
+   /** Allow databases with signatues that are unknown trust */
+   ALPM_SIG_DATABASE_UNKNOWN_OK = (1 << 13),
+
+   /** The Default siglevel */
+   ALPM_SIG_USE_DEFAULT = (1 << 30)
+} alpm_siglevel_t;
+
+/** PGP signature verification status return codes */
+typedef enum _alpm_sigstatus_t {
+   /** Signature is valid */
+   ALPM_SIGSTATUS_VALID,
+   /** The key has expired */
+   ALPM_SIGSTATUS_KEY_EXPIRED,
+   /** The signature has expired */
+   ALPM_SIGSTATUS_SIG_EXPIRED,
+   /** The key is not in the keyring */
+   ALPM_SIGSTATUS_KEY_UNKNOWN,
+   /** The key has been disabled */
+   ALPM_SIGSTATUS_KEY_DISABLED,
+   /** The signature is invalid */
+   ALPM_SIGSTATUS_INVALID
+} alpm_sigstatus_t;
+
+
+/** The trust level of a PGP key */
+typedef enum _alpm_sigvalidity_t {
+   /** The signature is fully trusted */
+   ALPM_SIGVALIDITY_FULL,
+   /** The signature is marginally trusted */
+   ALPM_SIGVALIDITY_MARGINAL,
+   /** The signature is never trusted */
+   ALPM_SIGVALIDITY_NEVER,
+   /** The signature has unknown trust */
+   ALPM_SIGVALIDITY_UNKNOWN
+} alpm_sigvalidity_t;
+
+/** A PGP key */
+typedef struct _alpm_pgpkey_t {
+   /** The actual key data */
+   void *data;
+   /** The key's fingerprint */
+   char *fingerprint;
+   /** UID of the key */
+   char *uid;
+   /** Name of the key's owner */
+   char *name;
+   /** Email of the key's owner */
+   char *email;
+   /** When the key was created */
+   alpm_time_t created;
+   /** When the key expires */
+   alpm_time_t expires;
+   /** The length of the key */
+   unsigned int length;
+   /** has the key been revoked */
+   unsigned int revoked;
+   /** A character representing the  encryption algorithm used by the 
public key
+*
+* ? = unknown
+* R = RSA
+* D = DSA
+* E = EDDSA
+*/
+   char pubkey_algo;
+} alpm_pgpkey_t;
+
+/**
+ * Signature result. Contains the key, status, and validity of a given
+ * signature.
+ */
+typedef struct _alpm_sigresult_t {
+   /** The key of the signature */
+   alpm_pgpkey_t key;
+   /** The status of the signature */
+   alpm_sigstatus_t status;
+   /** The validity of the signature */
+   alpm_sigvalidity_t validity;
+} alpm_sigresult_t;
+
+/**
+ * Signature list. Contains the number of signatures found and a pointer to an
+ * array of results. The array is of size count.
+ */
+typedef struct _alpm_siglist_t {
+   /** The amount of results in the array */
+   size_t count;
+   /** An array of sigresults */
+   alpm_sigresult_t *results;
+} alpm_siglist_t;
+
+/**
+ * Check the PGP signature for the given package file.
+ * @param pkg the package to check
+ * @param siglist a pointer to storage for signature results
+ * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred)
+ */
+int alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, alpm_siglist_t *siglist);
+
+/**
+ * Check the PGP signature for the given database.
+ * @param db the database to check
+ * @param siglist a pointer to storage for signature results

[pacman-dev] [PATCH 18/23] doc: configure doxygen

[morganamilo]

- only document public alpm items (alpm_*)
- hide typedef'd structs (_alpm_pkg_t shows as alpm_pkg_t)
- enable inline struct definitions (this stops having a man page for
  every single struct)
---
 doc/Doxyfile.in | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 78481dd5..e2101a28 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -53,7 +53,7 @@ DISTRIBUTE_GROUP_DOC   = NO
 SUBGROUPING= YES
 INLINE_GROUPED_CLASSES = NO
 INLINE_SIMPLE_STRUCTS  = NO
-TYPEDEF_HIDES_STRUCT   = NO
+TYPEDEF_HIDES_STRUCT   = YES
 SYMBOL_CACHE_SIZE  = 0
 LOOKUP_CACHE_SIZE  = 0
 #---
@@ -107,14 +107,14 @@ WARN_LOGFILE   =
 #---
 # configuration options related to the input files
 #---
-INPUT  = ../lib/libalpm/
+INPUT  = ../lib/libalpm/alpm.h ../lib/libalpm/alpm_list.h
 INPUT_ENCODING = UTF-8
 FILE_PATTERNS  =
 RECURSIVE  = NO
 EXCLUDE=
 EXCLUDE_SYMLINKS   = NO
 EXCLUDE_PATTERNS   =
-EXCLUDE_SYMBOLS=
+EXCLUDE_SYMBOLS= _alpm_* __alpm_*
 EXAMPLE_PATH   =
 EXAMPLE_PATTERNS   = *
 EXAMPLE_RECURSIVE  = NO
-- 
2.29.2

[pacman-dev] [PATCH 17/23] doc: move top level items into groups

[morganamilo]

---
 lib/libalpm/alpm.h | 13 +++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 4673f639..e9cc7c85 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -62,6 +62,7 @@ extern "C" {
 /** The libalpm context handle.
  *
  * This struct represents an instance of libalpm.
+ * @ingroup alpm_handle
  */
 typedef struct __alpm_handle_t alpm_handle_t;
 
@@ -81,6 +82,7 @@ typedef struct __alpm_handle_t alpm_handle_t;
  * the user. They will be freed when the database is unregistered.
  *
  * Databases are automatically unregistered when the \link alpm_handle_t 
\endlink is released.
+ * @ingroup alpm_databases
  */
 typedef struct __alpm_db_t alpm_db_t;
 
@@ -93,12 +95,20 @@ typedef struct __alpm_db_t alpm_db_t;
  *
  * Packages can then be queried for metadata or added to a \link alpm_trans_t 
transaction \endlink
  * to be added or removed from the system.
+ * @ingroup alpm_packages
  */
 typedef struct __alpm_pkg_t alpm_pkg_t;
 
-/** Transaction structure used internally by libalpm */
+/** Transaction structure used internally by libalpm 
+ * @ingroup alpm_trans
+ * */
 typedef struct __alpm_trans_t alpm_trans_t;
 
+
+/** The time type used by libalpm. Represents a unix time stamp
+ * @ingroup alpm_misc */
+typedef int64_t alpm_time_t;
+
 /** @addtogroup alpm_files Files
  * @brief Functions for package files
  * @{
@@ -343,7 +353,6 @@ int alpm_release(alpm_handle_t *handle);
 /* End of alpm_handle */
 /** @} */
 
-typedef int64_t alpm_time_t;
 
 /** @addtogroup alpm_sig Signature checking
  * @brief Functions to check signatures
-- 
2.29.2

[pacman-dev] [PATCH 21/23] doc: add extra documentation to the man page

[morganamilo]

---
 lib/libalpm/alpm.h  | 10 --
 lib/libalpm/alpm_list.h | 10 ++
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index a0de9b13..b2772f19 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -50,8 +50,14 @@ extern "C" {
 
 #include 
 
-/** @addtogroup alpm alpm
- * @brief The libalpm Public API
+/** @addtogroup alpm The libalpm Public API
+ *
+ * @section see_also See Also
+ * \b alpm_list(3),
+ * \b alpm-hooks(5),
+ * \b makepkg(8),
+ * \b pacman(8),
+ * \b pacman.conf(5)
  * @{
  */
 
diff --git a/lib/libalpm/alpm_list.h b/lib/libalpm/alpm_list.h
index 1eac3043..01fa092c 100644
--- a/lib/libalpm/alpm_list.h
+++ b/lib/libalpm/alpm_list.h
@@ -24,6 +24,16 @@
  * @author Pacman Development Team
  * @date 7 Dec 2020
  * @brief A doubly linked list for use with libalpm
+ *
+ * @section see_also See Also
+ * \b alpm(3),
+ * \b alpm-hooks(5),
+ * \b makepkg(8),
+ * \b pacman(8),
+ * \b pacman.conf(5)
+ * @{
+ */
+
  */
 
 #ifndef ALPM_LIST_H
-- 
2.29.2

[pacman-dev] [PATCH 11/23] doc: document files and groups

[morganamilo]

---
 lib/libalpm/alpm.h | 102 +
 1 file changed, 56 insertions(+), 46 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 5ee99711..30bfb06d 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -94,44 +94,82 @@ typedef struct __alpm_pkg_t alpm_pkg_t;
 /** Transaction structure used internally by libalpm */
 typedef struct __alpm_trans_t alpm_trans_t;
 
-/*
- * Structures
+/** @addtogroup alpm_api ALPM
+ * @brief The libalpm Public API
+ * @{
  */
 
-/** Package group */
-typedef struct _alpm_group_t {
-   /** group name */
-   char *name;
-   /** list of alpm_pkg_t packages */
-   alpm_list_t *packages;
-} alpm_group_t;
+/** @addtogroup alpm_files Files
+ * @brief Functions for package files
+ * @{
+ */
 
 /** File in a package */
 typedef struct _alpm_file_t {
-   char *name;
-   off_t size;
-   mode_t mode;
+   /** Name of the file */
+   char *name;
+   /** Size of the file */
+   off_t size;
+   /** The file's permissions */
+   mode_t mode;
 } alpm_file_t;
 
 /** Package filelist container */
 typedef struct _alpm_filelist_t {
-   size_t count;
-   alpm_file_t *files;
+   /** Amount of files in the array */
+   size_t count;
+   /** An array of files */
+   alpm_file_t *files;
 } alpm_filelist_t;
 
 /** Local package or package file backup entry */
 typedef struct _alpm_backup_t {
-   char *name;
-   char *hash;
+   /** Name of the file (without .pacsave extension) */
+   char *name;
+   /** Hash of the filename (used internally) */
+   char *hash;
 } alpm_backup_t;
 
+/** Determines whether a package filelist contains a given path.
+ * The provided path should be relative to the install root with no leading
+ * slashes, e.g. "etc/localtime". When searching for directories, the path must
+ * have a trailing slash.
+ * @param filelist a pointer to a package filelist
+ * @param path the path to search for in the package
+ * @return a pointer to the matching file or NULL if not found
+ */
+alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char 
*path);
+
+/* End of alpm_files */
+/** @} */
 
 
-/** @addtogroup alpm_api ALPM
- * @brief The libalpm Public API
+/** @addtogroup alpm_groups Groups
+ * @brief Functions for package groups
  * @{
  */
 
+/** Package group */
+typedef struct _alpm_group_t {
+   /** group name */
+   char *name;
+   /** list of alpm_pkg_t packages */
+   alpm_list_t *packages;
+} alpm_group_t;
+
+/** Find group members across a list of databases.
+ * If a member exists in several databases, only the first database is used.
+ * IgnorePkg is also handled.
+ * @param dbs the list of alpm_db_t *
+ * @param name the name of the group
+ * @return the list of alpm_pkg_t * (caller is responsible for alpm_list_free)
+ */
+alpm_list_t *alpm_find_group_pkgs(alpm_list_t *dbs, const char *name);
+
+/* End of alpm_groups */
+/** @} */
+
+
 /** @addtogroup alpm_errors Error Codes
  * Error codes returned by libalpm.
  * @{
@@ -2031,34 +2069,6 @@ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct 
archive *archive);
 /** @} */
 
 
-/*
- * Filelists
- */
-
-/** Determines whether a package filelist contains a given path.
- * The provided path should be relative to the install root with no leading
- * slashes, e.g. "etc/localtime". When searching for directories, the path must
- * have a trailing slash.
- * @param filelist a pointer to a package filelist
- * @param path the path to search for in the package
- * @return a pointer to the matching file or NULL if not found
- */
-alpm_file_t *alpm_filelist_contains(alpm_filelist_t *filelist, const char 
*path);
-
-
-/*
- * Groups
- */
-
-/** Find group members across a list of databases.
- * If a member exists in several databases, only the first database is used.
- * IgnorePkg is also handled.
- * @param dbs the list of alpm_db_t *
- * @param name the name of the group
- * @return the list of alpm_pkg_t * (caller is responsible for alpm_list_free)
- */
-alpm_list_t *alpm_find_group_pkgs(alpm_list_t *dbs, const char *name);
-
 /*
  * Sync
  */
-- 
2.29.2

[pacman-dev] [PATCH 20/23] doc: rename alpm_api group to alpm

[morganamilo]

---
 lib/libalpm/alpm.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index e9cc7c85..a0de9b13 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -50,7 +50,7 @@ extern "C" {
 
 #include 
 
-/** @addtogroup alpm_api ALPM
+/** @addtogroup alpm alpm
  * @brief The libalpm Public API
  * @{
  */
-- 
2.29.2

[pacman-dev] [PATCH 10/23] doc: document packages

[morganamilo]

---
 lib/libalpm/alpm.h | 164 ++---
 1 file changed, 96 insertions(+), 68 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index ea690abc..5ee99711 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -1368,43 +1368,11 @@ int alpm_db_get_usage(alpm_db_t *db, int *usage);
 /* End of usage accessors */
 /** @} */
 
+
 /* End of alpm_databases */
 /** @} */
 
 
-/*
- * Enumerations
- * These ones are used in multiple contexts, so are forward-declared.
- */
-
-/** Package install reasons. */
-typedef enum _alpm_pkgreason_t {
-   /** Explicitly requested by the user. */
-   ALPM_PKG_REASON_EXPLICIT = 0,
-   /** Installed as a dependency for another package. */
-   ALPM_PKG_REASON_DEPEND = 1
-} alpm_pkgreason_t;
-
-/** Location a package object was loaded from. */
-typedef enum _alpm_pkgfrom_t {
-   ALPM_PKG_FROM_FILE = 1,
-   ALPM_PKG_FROM_LOCALDB,
-   ALPM_PKG_FROM_SYNCDB
-} alpm_pkgfrom_t;
-
-/** Method used to validate a package. */
-typedef enum _alpm_pkgvalidation_t {
-   ALPM_PKG_VALIDATION_UNKNOWN = 0,
-   ALPM_PKG_VALIDATION_NONE = (1 << 0),
-   ALPM_PKG_VALIDATION_MD5SUM = (1 << 1),
-   ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2),
-   ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3)
-} alpm_pkgvalidation_t;
-
-/*
- * Logging facilities
- */
-
 /** \addtogroup alpm_log Logging Functions
  * @brief Functions to log using libalpm
  * @{
@@ -1446,17 +1414,6 @@ int alpm_logaction(alpm_handle_t *handle, const char 
*prefix,
 /* End of alpm_log */
 /** @} */
 
-/** Fetch a list of remote packages.
- * @param handle the context handle
- * @param urls list of package URLs to download
- * @param fetched list of filepaths to the fetched packages, each item
- *corresponds to one in `urls` list. This is an output parameter,
- *the caller should provide a pointer to an empty list
- *(*fetched === NULL) and the callee fills the list with data.
- * @return 0 on success or -1 on failure
- */
-int alpm_fetch_pkgurl(alpm_handle_t *handle, const alpm_list_t *urls,
- alpm_list_t **fetched);
 
 /** @addtogroup alpm_api_options Options
  * Libalpm option getters and setters
@@ -1638,11 +1595,44 @@ int alpm_option_set_parallel_downloads(alpm_handle_t 
*handle, unsigned int num_s
 
 /** @} */
 
-/** @addtogroup alpm_api_packages Package Functions
+/** @addtogroup alpm_packages Package Functions
  * Functions to manipulate libalpm packages
  * @{
  */
 
+/** Package install reasons. */
+typedef enum _alpm_pkgreason_t {
+   /** Explicitly requested by the user. */
+   ALPM_PKG_REASON_EXPLICIT = 0,
+   /** Installed as a dependency for another package. */
+   ALPM_PKG_REASON_DEPEND = 1
+} alpm_pkgreason_t;
+
+/** Location a package object was loaded from. */
+typedef enum _alpm_pkgfrom_t {
+   /** Loaded from a file via \link alpm_pkg_load \endlink */
+   ALPM_PKG_FROM_FILE = 1,
+   /** From the local database */
+   ALPM_PKG_FROM_LOCALDB,
+   /** From a sync database */
+   ALPM_PKG_FROM_SYNCDB
+} alpm_pkgfrom_t;
+
+
+/** Method used to validate a package. */
+typedef enum _alpm_pkgvalidation_t {
+   /** The package's validation type is unknown */
+   ALPM_PKG_VALIDATION_UNKNOWN = 0,
+   /** The package does not have any validation */
+   ALPM_PKG_VALIDATION_NONE = (1 << 0),
+   /** The package is validated with md5 */
+   ALPM_PKG_VALIDATION_MD5SUM = (1 << 1),
+   /** The package is validated with sha256 */
+   ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2),
+   /** The package is validated with a PGP signature */
+   ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3)
+} alpm_pkgvalidation_t;
+
 /** Create a package from a file.
  * If full is false, the archive is read only until all necessary
  * metadata is found. If it is true, the entire archive is read, which
@@ -1660,6 +1650,18 @@ int alpm_option_set_parallel_downloads(alpm_handle_t 
*handle, unsigned int num_s
 int alpm_pkg_load(alpm_handle_t *handle, const char *filename, int full,
int level, alpm_pkg_t **pkg);
 
+/** Fetch a list of remote packages.
+ * @param handle the context handle
+ * @param urls list of package URLs to download
+ * @param fetched list of filepaths to the fetched packages, each item
+ *corresponds to one in `urls` list. This is an output parameter,
+ *the caller should provide a pointer to an empty list
+ *(*fetched === NULL) and the callee fills the list with data.
+ * @return 0 on success or -1 on failure
+ */
+int alpm_fetch_pkgurl(alpm_handle_t *handle, const alpm_list_t *urls,
+ alpm_list_t **fetched);
+
 /** Find a package in a list by name.
  * @param haystack a list of alpm_pkg_t
  * @param needle the package name
@@ -1668,6 +1670,8 @@ int alpm_pkg_load(alpm_handle_t *handle, const char 
*filename, int full,
 alpm_pkg_t *alpm_pkg_find(alpm_list_t *haystack, const char *needle);
 
 /** Free a package.
+ * Only packages 

[pacman-dev] [PATCH 16/23] doc: move alpm_api group to top of file

[morganamilo]

---
 lib/libalpm/alpm.h | 10 +-
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 05dec6c7..4673f639 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -50,6 +50,11 @@ extern "C" {
 
 #include 
 
+/** @addtogroup alpm_api ALPM
+ * @brief The libalpm Public API
+ * @{
+ */
+
 /*
  * Opaque Structures
  */
@@ -94,11 +99,6 @@ typedef struct __alpm_pkg_t alpm_pkg_t;
 /** Transaction structure used internally by libalpm */
 typedef struct __alpm_trans_t alpm_trans_t;
 
-/** @addtogroup alpm_api ALPM
- * @brief The libalpm Public API
- * @{
- */
-
 /** @addtogroup alpm_files Files
  * @brief Functions for package files
  * @{
-- 
2.29.2

[pacman-dev] [PATCH 22/23] doc: change group names to libalpm_*

[morganamilo]

Also change the group's title to point to the group's man page.

This makes generated man pages be named libalpm_* which is more
consistent with what library man pages are usually called.
---
 doc/meson.build |  1 -
 lib/libalpm/alpm.h  | 80 +
 lib/libalpm/alpm_list.h | 22 ++--
 3 files changed, 53 insertions(+), 50 deletions(-)

diff --git a/doc/meson.build b/doc/meson.build
index e24172fd..570dc765 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -9,7 +9,6 @@ manpages = [
   { 'name': 'PKGBUILD.5', 'extra_depends' : [ 'PKGBUILD-example.txt' ] },
   { 'name': 'makepkg.conf.5' },
   { 'name': 'pacman.conf.5' },
-  { 'name': 'libalpm.3' },
   { 'name': 'BUILDINFO.5' },
   { 'name': 'pacman-conf.8' },
 ]
diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index b2772f19..dd28b191 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -21,13 +21,6 @@
  *  along with this program.  If not, see .
  */
 
-/**
- * @file alpm.h
- * @author Pacman Development Team
- * @date 7 Dec 2020
- * @brief Arch Linux Package Manager Library
- */
-
 /** @mainpage alpm
  *
  * libalpm is a package management library, primaraly used by pacman.
@@ -50,14 +43,41 @@ extern "C" {
 
 #include 
 
-/** @addtogroup alpm The libalpm Public API
+/** @addtogroup libalpm The libalpm Public API
+ *
+ *
+ * libalpm is a package management library, primaraly used by pacman.
+ *
+ * For ease of access, the libalpm manual has been split up into several 
sections.
  *
- * @section see_also See Also
- * \b alpm_list(3),
+ * @section bugs Bugs
+ * Bugs? You must be kidding; there are no bugs in this software. But if we 
happen to be wrong,
+ * submit a bug report with as much detail as possible at the Arch Linux Bug 
Tracker in the
+ * Pacman section.
+ *
+ * @section see_also See also
+ * \b libalpm-list(3),
  * \b alpm-hooks(5),
  * \b makepkg(8),
- * \b pacman(8),
- * \b pacman.conf(5)
+ *
+ * @section maintainers Maintainers
+ * Current maintainers:
+ *
+ * - Allan McRae 
+ * - Andrew Gregory 
+ * - Dave Reisner 
+ * - Eli Schwartz 
+ *
+ * Past major contributors:
+ *
+ * - Judd Vinet 
+ * - Aurelien Foret 
+ * - Aaron Griffin 
+ * - Dan McGee 
+ * - Xavier Chantry 
+ * - Nagy Gabor 
+ *
+ * For additional contributors, use git shortlog -s on the pacman.git 
repository.
  * @{
  */
 
@@ -68,7 +88,7 @@ extern "C" {
 /** The libalpm context handle.
  *
  * This struct represents an instance of libalpm.
- * @ingroup alpm_handle
+ * @ingroup libalpm-handle
  */
 typedef struct __alpm_handle_t alpm_handle_t;
 
@@ -88,7 +108,7 @@ typedef struct __alpm_handle_t alpm_handle_t;
  * the user. They will be freed when the database is unregistered.
  *
  * Databases are automatically unregistered when the \link alpm_handle_t 
\endlink is released.
- * @ingroup alpm_databases
+ * @ingroup libalpm-databases
  */
 typedef struct __alpm_db_t alpm_db_t;
 
@@ -101,21 +121,21 @@ typedef struct __alpm_db_t alpm_db_t;
  *
  * Packages can then be queried for metadata or added to a \link alpm_trans_t 
transaction \endlink
  * to be added or removed from the system.
- * @ingroup alpm_packages
+ * @ingroup libalpm-packages
  */
 typedef struct __alpm_pkg_t alpm_pkg_t;
 
 /** Transaction structure used internally by libalpm 
- * @ingroup alpm_trans
+ * @ingroup libalpm-trans
  * */
 typedef struct __alpm_trans_t alpm_trans_t;
 
 
 /** The time type used by libalpm. Represents a unix time stamp
- * @ingroup alpm_misc */
+ * @ingroup libalpm-misc */
 typedef int64_t alpm_time_t;
 
-/** @addtogroup alpm_files Files
+/** @addtogroup libalpm-files libalpm-files(3)
  * @brief Functions for package files
  * @{
  */
@@ -160,7 +180,7 @@ alpm_file_t *alpm_filelist_contains(alpm_filelist_t 
*filelist, const char *path)
 /** @} */
 
 
-/** @addtogroup alpm_groups Groups
+/** @addtogroup libalpm-groups libalpm-groups(3)
  * @brief Functions for package groups
  * @{
  */
@@ -186,7 +206,7 @@ alpm_list_t *alpm_find_group_pkgs(alpm_list_t *dbs, const 
char *name);
 /** @} */
 
 
-/** @addtogroup alpm_errors Error Codes
+/** @addtogroup libalpm-errors libalpm-errors(3)
  * Error codes returned by libalpm.
  * @{
  */
@@ -330,7 +350,7 @@ const char *alpm_strerror(alpm_errno_t err);
 /** @} */
 
 
-/** \addtogroup alpm_handle Handle
+/** \addtogroup libalpm-handle libalpm-handle(3)
  * @brief Functions to initialize and release libalpm
  * @{
  */
@@ -360,7 +380,7 @@ int alpm_release(alpm_handle_t *handle);
 /** @} */
 
 
-/** @addtogroup alpm_sig Signature checking
+/** @addtogroup libalpm-sig libalpm-sig(3)
  * @brief Functions to check signatures
  * @{
  */
@@ -526,7 +546,7 @@ int alpm_extract_keyid(alpm_handle_t *handle, const char 
*identifier,
 /** @} */
 
 
-/** @addtogroup alpm_depends Dependency
+/** @addtogroup libalpm-depends libalpm-depends(3)
  * @brief Functions dealing with libalpm's dependency and conflict
  * information.
  * @{
@@ -703,7 +723,7 @@ void 

[pacman-dev] [PATCH 13/23] doc: document misc

[morganamilo]

---
 lib/libalpm/alpm.h | 35 ---
 1 file changed, 20 insertions(+), 15 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 76ae5722..494a8319 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -2068,11 +2068,6 @@ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct 
archive *archive);
 /* End of alpm_packages */
 /** @} */
 
-/** Check for new version of pkg in sync repos
- * (only the first occurrence is considered in sync)
- */
-alpm_pkg_t *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync);
-
 /** @addtogroup alpm_trans Transaction
  * @brief Functions to manipulate libalpm transactions
  *
@@ -2212,20 +2207,25 @@ int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t 
*pkg);
 /* End of add/remove packages */
 /** @} */
 
+
 /* End of alpm_trans */
 /** @} */
 
-/*
- * Helpers
- */
-
-/* checksums */
 
 /** \addtogroup alpm_misc Miscellaneous Functions
  * @brief Various libalpm functions
  * @{
  */
 
+/** Check for new version of pkg in syncdbs.
+ *
+ * If the same package appears multiple dbs only the first will be checked
+ *
+ * This only checks the syncdb for a newer version. It does not access the 
network at all.
+ * See \link alpm_db_update \endlink to update a database.
+ */
+alpm_pkg_t *alpm_sync_get_new_version(alpm_pkg_t *pkg, alpm_list_t *dbs_sync);
+
 /** Get the md5 sum of file.
  * @param filename name of the file
  * @return the checksum on success, NULL on error
@@ -2238,8 +2238,6 @@ char *alpm_compute_md5sum(const char *filename);
  */
 char *alpm_compute_sha256sum(const char *filename);
 
-/** @} */
-
 /** Remove the database lock file
  * @param handle the context handle
  * @return 0 on success, -1 on error
@@ -2248,10 +2246,14 @@ char *alpm_compute_sha256sum(const char *filename);
  */
 int alpm_unlock(alpm_handle_t *handle);
 
+/** Enum of possible compile time features */
 enum alpm_caps {
-   ALPM_CAPABILITY_NLS = (1 << 0),
-   ALPM_CAPABILITY_DOWNLOADER = (1 << 1),
-   ALPM_CAPABILITY_SIGNATURES = (1 << 2)
+/** localization */
+ALPM_CAPABILITY_NLS = (1 << 0),
+/** Ability to download */
+ALPM_CAPABILITY_DOWNLOADER = (1 << 1),
+/** Signature checking */
+ALPM_CAPABILITY_SIGNATURES = (1 << 2)
 };
 
 /** Get the version of library.
@@ -2264,6 +2266,9 @@ const char *alpm_version(void);
  * */
 int alpm_capabilities(void);
 
+/* End of alpm_misc */
+/** @} */
+
 /* End of alpm_api */
 /** @} */
 
-- 
2.29.2

[pacman-dev] [PATCH 23/23] doc: remove old libalpm man file

[morganamilo]

---
 doc/libalpm.3.asciidoc | 37 -
 1 file changed, 37 deletions(-)
 delete mode 100644 doc/libalpm.3.asciidoc

diff --git a/doc/libalpm.3.asciidoc b/doc/libalpm.3.asciidoc
deleted file mode 100644
index 79ea5409..
--- a/doc/libalpm.3.asciidoc
+++ /dev/null
@@ -1,37 +0,0 @@
-libalpm(3)
-==
-
-Name
-
-libalpm - Arch Linux Package Management (ALPM) library
-
-
-Synopsis
-
-For ease of access, the libalpm manual has been split up into several sections.
-
-*TODO:* Yes, this man page needs a lot of work. Once we get around to doing
-good Doxygen documentation, it will improve. We promise.
-
-*alpm_databases*:: Database Functions
-*alpm_interface*:: Interface Functions
-*alpm_list*::  List Functions
-*alpm_log*::   Logging Functions
-*alpm_misc*::  Miscellaneous Functions
-*alpm_packages*::  Package Functions
-*alpm_sync*::  Sync Functions
-*alpm_trans*:: Transaction Functions
-
-
-Configuration
--
-See linkman:pacman.conf[5] for more details on configuring libalpm using the
-'pacman.conf' file.
-
-
-See Also
-
-linkman:alpm-hooks[5], linkman:makepkg[8], linkman:pacman[8],
-linkman:pacman.conf[5]
-
-include::footer.asciidoc[]
-- 
2.29.2

[pacman-dev] [PATCH 04/23] doc: document handle

[morganamilo]

---
 lib/libalpm/alpm.h | 58 --
 1 file changed, 30 insertions(+), 28 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 1c2422ca..178c8f6a 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -243,6 +243,36 @@ const char *alpm_strerror(alpm_errno_t err);
 /* End of alpm_errors */
 /** @} */
 
+
+/** \addtogroup alpm_handle Handle
+ * @brief Functions to initialize and release libalpm
+ * @{
+ */
+
+/** Initializes the library.
+ * Creates handle, connects to database and creates lockfile.
+ * This must be called before any other functions are called.
+ * @param root the root path for all filesystem operations
+ * @param dbpath the absolute path to the libalpm database
+ * @param err an optional variable to hold any error return codes
+ * @return a context handle on success, NULL on error, err will be set if 
provided
+ */
+alpm_handle_t *alpm_initialize(const char *root, const char *dbpath,
+   alpm_errno_t *err);
+
+/** Release the library.
+ * Disconnects from the database, removes handle and lockfile
+ * This should be the last alpm call you make.
+ * After this returns, handle should be considered invalid and cannot be reused
+ * in any way.
+ * @param myhandle the context handle
+ * @return 0 on success, -1 on error
+ */
+int alpm_release(alpm_handle_t *handle);
+
+/* End of alpm_handle */
+/** @} */
+
 typedef int64_t alpm_time_t;
 
 /*
@@ -1915,34 +1945,6 @@ char *alpm_compute_sha256sum(const char *filename);
 
 /** @} */
 
-/** \addtogroup alpm_interface Interface Functions
- * @brief Functions to initialize and release libalpm
- * @{
- */
-
-/** Initializes the library.
- * Creates handle, connects to database and creates lockfile.
- * This must be called before any other functions are called.
- * @param root the root path for all filesystem operations
- * @param dbpath the absolute path to the libalpm database
- * @param err an optional variable to hold any error return codes
- * @return a context handle on success, NULL on error, err will be set if 
provided
- */
-alpm_handle_t *alpm_initialize(const char *root, const char *dbpath,
-   alpm_errno_t *err);
-
-/** Release the library.
- * Disconnects from the database, removes handle and lockfile
- * This should be the last alpm call you make.
- * After this returns, handle should be considered invalid and cannot be reused
- * in any way.
- * @param myhandle the context handle
- * @return 0 on success, -1 on error
- */
-int alpm_release(alpm_handle_t *handle);
-
-/** @} */
-
 /** Remove the database lock file
  * @param handle the context handle
  * @return 0 on success, -1 on error
-- 
2.29.2

[pacman-dev] [PATCH 03/23] doc: document error

[morganamilo]

---
 lib/libalpm/alpm.h | 122 -
 1 file changed, 109 insertions(+), 13 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 48ba7fdc..1c2422ca 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -51,102 +51,198 @@ extern "C" {
 #include 
 
 /*
- * Arch Linux Package Management library
+ * Opaque Structures
  */
 
-/*
- * Opaque Structures
+/** The libalpm context handle.
+ *
+ * This struct represents an instance of libalpm.
  */
 typedef struct __alpm_handle_t alpm_handle_t;
+
+/** A database.
+ *
+ * A database is a container that stores metadata about packages.
+ *
+ * A database can be located on the local filesystem or on a remote server.
+ *
+ * To use a database, it must first be registered via \link 
alpm_register_syncdb \endlink.
+ * If the database is already preasant in dbpath then it will be usable. 
Otherwise,
+ * the database needs to be downloaded using \link alpm_db_update \endlink. 
Even if the
+ * source of the database is the local filesystem.
+ *
+ * After this, the database can be used to query packages and groups. Any 
packages or groups
+ * from the database will continue to be owned by the database and do not need 
to be freed by
+ * the user. They will be freed when the database is unregistered.
+ *
+ * Databases are automatically unregistered when the \link alpm_handle_t 
\endlink is released.
+ */
 typedef struct __alpm_db_t alpm_db_t;
+
+
+/** A package
+ *
+ * A package can be loaded from disk via \link alpm_pkg_load \endlink or 
retrieved from a database.
+ * Packages from databases are automatically freed when the database is 
unregistered. Packages loaded
+ * from a file must be freed manually.
+ *
+ * Packages can then be queried for metadata or added to a \link alpm_trans_t 
transaction \endlink
+ * to be added or removed from the system.
+ */
 typedef struct __alpm_pkg_t alpm_pkg_t;
+
+/** Transaction structure used internally by libalpm */
 typedef struct __alpm_trans_t alpm_trans_t;
 
-/** @addtogroup alpm_api_errors Error Codes
+
+/** @addtogroup alpm_api ALPM
+ * @brief The libalpm Public API
+ * @{
+ */
+
+/** @addtogroup alpm_errors Error Codes
+ * Error codes returned by libalpm.
  * @{
  */
+
+/** libalpm's error type */
 typedef enum _alpm_errno_t {
+   /** No error */
ALPM_ERR_OK = 0,
+   /** Failed to allocate memory */
ALPM_ERR_MEMORY,
+   /** A system error occurred */
ALPM_ERR_SYSTEM,
+   /** Permmision denied */
ALPM_ERR_BADPERMS,
+   /** Should be a file */
ALPM_ERR_NOT_A_FILE,
+   /** Should be a directory */
ALPM_ERR_NOT_A_DIR,
+   /** Function was called with invalid arguments */
ALPM_ERR_WRONG_ARGS,
+   /** Insufficient disk space */
ALPM_ERR_DISK_SPACE,
/* Interface */
+   /** Handle should be null */
ALPM_ERR_HANDLE_NULL,
+   /** Handle should not be null */
ALPM_ERR_HANDLE_NOT_NULL,
+   /** Failed to acquire lock */
ALPM_ERR_HANDLE_LOCK,
/* Databases */
+   /** Failed to open database */
ALPM_ERR_DB_OPEN,
+   /** Failed to create database */
ALPM_ERR_DB_CREATE,
+   /** Database should not be null */
ALPM_ERR_DB_NULL,
+   /** Database should be null */
ALPM_ERR_DB_NOT_NULL,
+   /** The database could not be found */
ALPM_ERR_DB_NOT_FOUND,
+   /** Database is invalid */
ALPM_ERR_DB_INVALID,
+   /** Database has an invalid signature */
ALPM_ERR_DB_INVALID_SIG,
+   /** The localdb is in a newer/older format than libalpm expects */
ALPM_ERR_DB_VERSION,
+   /** Failed to write to the database */
ALPM_ERR_DB_WRITE,
+   /** Failed to remove entry from database */
ALPM_ERR_DB_REMOVE,
/* Servers */
+   /** Server URL is in an invalid format */
ALPM_ERR_SERVER_BAD_URL,
+   /** The database has no configured servers */
ALPM_ERR_SERVER_NONE,
/* Transactions */
+   /** A transaction is already initialized */
ALPM_ERR_TRANS_NOT_NULL,
+   /** A transaction has not been initialized */
ALPM_ERR_TRANS_NULL,
+   /** Duplicate target in transaction */
ALPM_ERR_TRANS_DUP_TARGET,
+   /** A transaction has not been initialized */
ALPM_ERR_TRANS_NOT_INITIALIZED,
+   /** Transaction has not been prepared */
ALPM_ERR_TRANS_NOT_PREPARED,
+   /** Transaction was aborted */
ALPM_ERR_TRANS_ABORT,
+   /** Failed to interrupt transaction */
ALPM_ERR_TRANS_TYPE,
+   /** Tried to commit transaction without locking the database */
ALPM_ERR_TRANS_NOT_LOCKED,
+   /** A hook failed to run */
ALPM_ERR_TRANS_HOOK_FAILED,
/* Packages */
+   /** Package not found */
ALPM_ERR_PKG_NOT_FOUND,
+   /** Package is in ignorepkg */
ALPM_ERR_PKG_IGNORED,
+   /** Package is invalid */
  

[pacman-dev] [PATCH 02/23] doc: add doc header to alpm.h

[morganamilo]

---
 lib/libalpm/alpm.h | 13 +
 1 file changed, 13 insertions(+)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 50c4bb6b..48ba7fdc 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -20,6 +20,19 @@
  *  You should have received a copy of the GNU General Public License
  *  along with this program.  If not, see .
  */
+
+/**
+ * @file alpm.h
+ * @author Pacman Development Team
+ * @date 7 Dec 2020
+ * @brief Arch Linux Package Manager Library
+ */
+
+/** @mainpage alpm
+ *
+ * libalpm is a package management library, primaraly used by pacman.
+ */
+
 #ifndef ALPM_H
 #define ALPM_H
 
-- 
2.29.2

[pacman-dev] [PATCH 00/23] Docs Docs Docs 2: electric boogaloo

[morganamilo]

Here's a redo of my original docs patch and more.

This time it's split in to many commits so it's hopefully easier to
review/rebase.

Every function, struct and param is now documented.

Simply `man libalpm` to get the main page. Then `man libalpm-databases`
to see the database section and so on for each section.

Also while doing all this, I thought it would make sense to change some
function names:

I also think alpm_unlock() should be named alpm_db_unlock() and
alpm_sync_get_new_version() should be named alpm_pkg_get_new_version()

Then the functions could be moved into the db and packages groups
repectivley.

To be clear I have not actually changed any function names in this patch
set.

morganamilo (23):
  doc: remove stray doxygen comment
  doc: add doc header to alpm.h
  doc: document error
  doc: document handle
  doc: document signatures
  doc: document depends
  doc: document callbacks
  doc: document databases
  doc: document logging
  doc: document packages
  doc: document files and groups
  doc: document transactions
  doc: document misc
  doc: document alpm_list
  doc: document options
  doc: move alpm_api group to top of file
  doc: move top level items into groups
  doc: configure doxygen
  doc: update doxyfile
  doc: rename alpm_api group to alpm
  doc: add extra documentation to the man page
  doc: change group names to libalpm_*
  doc: remove old libalpm man file

 doc/Doxyfile.in |   83 +-
 doc/libalpm.3.asciidoc  |   37 -
 doc/meson.build |1 -
 lib/libalpm/alpm.h  | 2429 +++
 lib/libalpm/alpm_list.c |  251 
 lib/libalpm/alpm_list.h |  293 -
 lib/libalpm/trans.c |2 -
 7 files changed, 2048 insertions(+), 1048 deletions(-)
 delete mode 100644 doc/libalpm.3.asciidoc

-- 
2.29.2

[pacman-dev] [PATCH 01/23] doc: remove stray doxygen comment

[morganamilo]

---
 lib/libalpm/trans.c | 2 --
 1 file changed, 2 deletions(-)

diff --git a/lib/libalpm/trans.c b/lib/libalpm/trans.c
index c7317c15..303d2fca 100644
--- a/lib/libalpm/trans.c
+++ b/lib/libalpm/trans.c
@@ -266,8 +266,6 @@ int SYMEXPORT alpm_trans_release(alpm_handle_t *handle)
return 0;
 }
 
-/** @} */
-
 void _alpm_trans_free(alpm_trans_t *trans)
 {
if(trans == NULL) {
-- 
2.29.2

Re: [pacman-dev] Remove skipped warning message for already installed packages when --needed is specified?

[Daan De Meyer]

To give a bit more context, the key insight here is that mkosi is a
script that invokes pacman with a list of packages supplied by the
user (in this case -> systemd). mkosi first provisions a base Arch
image and then installs the packages listed by systemd in it's mkosi
config file (https://github.com/systemd/systemd/blob/master/.mkosi/mkosi.arch).
To be on the safe side, the config file lists all build dependencies
of systemd as build packages so that the mkosi config keeps working
regardless of which packages are installed in a base Arch install.
Because of this approach, users get quite a few warnings from Pacman
when running mkosi (one for each package in BuildPackages that's
already installed in the base image). I was hoping --needed would
silence these warnings as well. Of course, I could add logic to
systemd to filter out the duplicate packages by calling into pacman
and filtering existing packages out of the list we install but if
pacman didn't warn when using --needed, we'd be able to save us a
little bit of complexity.

Thinking about this further, If a user always knew exactly which of
the packages he was installing were already installed, there wouldn't
be a need for --needed (no pun intended) as the user could simply
remove those packages from the list of packages passed to pacman. To
me, --needed seems useful exactly in the case where a user doesn't
know which packages are already installed and which aren't, which
makes the warning a bit moot as the reason we're using --needed is
exactly because we don't know which ones are already installed and
want to delegate the complexity of finding that out and only
installing the packages that aren't already installed to pacman.

I hope that makes sense.

Daan

On Sun, 6 Dec 2020 at 23:22, Allan McRae  wrote:
>
> On 7/12/20 5:05 am, Daan De Meyer wrote:
> > Hi,
> >
> > I recently added --needed to pacman's invocation in mkosi but noticed
> > that even when --needed is specified, pacman still prints warning
> > messages for packages that it's skipping because they are already
> > installed. My intuition was that by enabling --needed, I was
> > explicitly telling pacman that there might be packages that are
> > already installed in the packages that I'm installing and that I want
> > to skip those and not be warned about them. The skipping works fine
> > but I still get warnings. Would it make sense to remove the skipped
> > warning message for packages that are already installed when --needed
> > is specified since the user is explicitly requesting this behavior?
> >
>
> I'm on the fence here.  You have explicitly asked for packages to be
> installed by providing them on the command line, but then --needed says
> they don't need installed.  That does seem warning-ish to me.
>
> Allan

Re: [pacman-dev] [PATCH] Add --confirm

[Allan McRae]

On 7/12/20 7:21 pm, morganamilo wrote:
> this is useful for cancelling the automatically passed --noconfirm
> by makechrootpkg

Please explain why I should care what makechrootpkg does?

> 
> diff --git a/doc/makepkg.8.asciidoc b/doc/makepkg.8.asciidoc
> index 3b5e61b3..b3ecbe12 100644
> --- a/doc/makepkg.8.asciidoc
> +++ b/doc/makepkg.8.asciidoc
> @@ -184,6 +184,9 @@ Options
>   (Passed to pacman) Prevent pacman from waiting for user input before
>   proceeding with operations.
>  
> +*\--confirm*::
> + Cancels the effects of a previous --noconfirm.
> +
>  *\--needed*::
>   (Passed to pacman) Tell pacman not to reinstall a target if it is 
> already
>   up-to-date. (used with '-i' / '\--install').
> diff --git a/scripts/makepkg.sh.in b/scripts/makepkg.sh.in
> index b39433f3..1c8e8a0e 100644
> --- a/scripts/makepkg.sh.in
> +++ b/scripts/makepkg.sh.in
> @@ -997,6 +997,7 @@ usage() {
>   printf -- "$(gettext "  --asdeps Install packages as 
> non-explicitly installed")\n"
>   printf -- "$(gettext "  --needed Do not reinstall the targets 
> that are already up to date")\n"
>   printf -- "$(gettext "  --noconfirm  Do not ask for confirmation 
> when resolving dependencies")\n"
> + printf -- "$(gettext "  --confirmCancels the effects of a 
> previous --noconfirm")\n"
>   printf -- "$(gettext "  --noprogressbar  Do not show a progress bar 
> when downloading files")\n"
>   echo
>   printf -- "$(gettext "If %s is not specified, %s will look for 
> '%s'")\n" "-p" "makepkg" "$BUILDSCRIPT"
> @@ -1036,7 +1037,7 @@ OPT_LONG=('allsource' 'check' 'clean' 'cleanbuild' 
> 'config:' 'force' 'geninteg'
>'skippgpcheck' 'source' 'syncdeps' 'verifysource' 'version')
>  
>  # Pacman Options
> -OPT_LONG+=('asdeps' 'noconfirm' 'needed' 'noprogressbar')
> +OPT_LONG+=('asdeps' 'confirm' 'noconfirm' 'needed' 'noprogressbar')
>  
>  if ! parseopts "$OPT_SHORT" "${OPT_LONG[@]}" -- "$@"; then
>   exit $E_INVALID_OPTION
> @@ -1050,6 +1051,7 @@ while true; do
>   --asdeps) ASDEPS=1;;
>   --needed) NEEDED=1;;
>   --noconfirm)  PACMAN_OPTS+=("--noconfirm") ;;
> + --confirm)PACMAN_OPTS+=("--confirm") ;;
>   --noprogressbar)  PACMAN_OPTS+=("--noprogressbar") ;;
>  
>   # Makepkg Options
> 

[pacman-dev] [PATCH] Add --confirm

[morganamilo]

this is useful for cancelling the automatically passed --noconfirm
by makechrootpkg

diff --git a/doc/makepkg.8.asciidoc b/doc/makepkg.8.asciidoc
index 3b5e61b3..b3ecbe12 100644
--- a/doc/makepkg.8.asciidoc
+++ b/doc/makepkg.8.asciidoc
@@ -184,6 +184,9 @@ Options
(Passed to pacman) Prevent pacman from waiting for user input before
proceeding with operations.
 
+*\--confirm*::
+   Cancels the effects of a previous --noconfirm.
+
 *\--needed*::
(Passed to pacman) Tell pacman not to reinstall a target if it is 
already
up-to-date. (used with '-i' / '\--install').
diff --git a/scripts/makepkg.sh.in b/scripts/makepkg.sh.in
index b39433f3..1c8e8a0e 100644
--- a/scripts/makepkg.sh.in
+++ b/scripts/makepkg.sh.in
@@ -997,6 +997,7 @@ usage() {
printf -- "$(gettext "  --asdeps Install packages as 
non-explicitly installed")\n"
printf -- "$(gettext "  --needed Do not reinstall the targets 
that are already up to date")\n"
printf -- "$(gettext "  --noconfirm  Do not ask for confirmation 
when resolving dependencies")\n"
+   printf -- "$(gettext "  --confirmCancels the effects of a 
previous --noconfirm")\n"
printf -- "$(gettext "  --noprogressbar  Do not show a progress bar 
when downloading files")\n"
echo
printf -- "$(gettext "If %s is not specified, %s will look for 
'%s'")\n" "-p" "makepkg" "$BUILDSCRIPT"
@@ -1036,7 +1037,7 @@ OPT_LONG=('allsource' 'check' 'clean' 'cleanbuild' 
'config:' 'force' 'geninteg'
   'skippgpcheck' 'source' 'syncdeps' 'verifysource' 'version')
 
 # Pacman Options
-OPT_LONG+=('asdeps' 'noconfirm' 'needed' 'noprogressbar')
+OPT_LONG+=('asdeps' 'confirm' 'noconfirm' 'needed' 'noprogressbar')
 
 if ! parseopts "$OPT_SHORT" "${OPT_LONG[@]}" -- "$@"; then
exit $E_INVALID_OPTION
@@ -1050,6 +1051,7 @@ while true; do
--asdeps) ASDEPS=1;;
--needed) NEEDED=1;;
--noconfirm)  PACMAN_OPTS+=("--noconfirm") ;;
+   --confirm)PACMAN_OPTS+=("--confirm") ;;
--noprogressbar)  PACMAN_OPTS+=("--noprogressbar") ;;
 
# Makepkg Options
-- 
2.29.2