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

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(-)

On 8/12/20 8:19 am, morganamilo wrote:
> 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.
> ---

I have applied all patches up to this point.  Bit confiused about a
section below:

>  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 <http://www.gnu.org/licenses/>.
>   */
>  
> -/**
> - * @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 <alpm_list.h>
>  
> -/** @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)
> + *

There seems to be a lot of duplication from our footer.asciidoc here.  Why?

> + * @section maintainers Maintainers
> + * Current maintainers:
> + *
> + * - Allan McRae <allan@archlinux.org>
> + * - Andrew Gregory <andrew.gregory.8@gmail.com>
> + * - Dave Reisner <dreisner@archlinux.org>
> + * - Eli Schwartz <eschwartz@archlinux.org>
> + *
> + * Past major contributors:
> + *
> + * - Judd Vinet <jvinet@zeroflux.org>
> + * - Aurelien Foret <aurelien@archlinux.org>
> + * - Aaron Griffin <aaron@archlinux.org>
> + * - Dan McGee <dan@archlinux.org>
> + * - Xavier Chantry <shiningxc@gmail.com>
> + * - Nagy Gabor <ngaba@bibl.u-szeged.hu>
> + *
> + * 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 alpm_conflict_free(alpm_conflict_t *conflict);
>  /** @} */
>  
>  
> -/** \addtogroup alpm_cb Callbacks
> +/** \addtogroup libalpm-cb libalpm-cb(3)
>   * @brief Functions and structures for libalpm's callbacks
>   * @{
>   */
> @@ -1208,7 +1228,7 @@ typedef int (*alpm_cb_fetch)(const char *url, const char *localpath,
>  /** @} */
>  
>  
> -/** @addtogroup alpm_databases Database
> +/** @addtogroup libalpm-databases libalpm-database(3)
>   * @brief Functions to query and manipulate the database of libalpm.
>   * @{
>   */
> @@ -1426,7 +1446,7 @@ int alpm_db_get_usage(alpm_db_t *db, int *usage);
>  /** @} */
>  
>  
> -/** \addtogroup alpm_log Logging Functions
> +/** \addtogroup libalpm-log alpm-log(3)
>   * @brief Functions to log using libalpm
>   * @{
>   */
> @@ -1468,7 +1488,7 @@ int alpm_logaction(alpm_handle_t *handle, const char *prefix,
>  /** @} */
>  
>  
> -/** @addtogroup alpm_options Options
> +/** @addtogroup libalpm-options libalpm-options(3)
>   * Libalpm option getters and setters
>   * @{
>   */
> @@ -2184,7 +2204,7 @@ int alpm_option_set_parallel_downloads(alpm_handle_t *handle, unsigned int num_s
>  /** @} */
>  
>  
> -/** @addtogroup alpm_packages Package Functions
> +/** @addtogroup libalpm-packages libalpm-packages(3)
>   * Functions to manipulate libalpm packages
>   * @{
>   */
> @@ -2619,7 +2639,7 @@ int alpm_pkg_mtree_close(const alpm_pkg_t *pkg, struct archive *archive);
>  /* End of alpm_packages */
>  /** @} */
>  
> -/** @addtogroup alpm_trans Transaction
> +/** @addtogroup libalpm-trans libalpm-trans(3)
>   * @brief Functions to manipulate libalpm transactions
>   *
>   * Transactions are the way to add/remove packages to/from the system.
> @@ -2763,7 +2783,7 @@ int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg);
>  /** @} */
>  
>  
> -/** \addtogroup alpm_misc Miscellaneous Functions
> +/** \addtogroup libalpm-misc libalpm-misc(3)
>   * @brief Various libalpm functions
>   * @{
>   */
> diff --git a/lib/libalpm/alpm_list.h b/lib/libalpm/alpm_list.h
> index 01fa092c..620cfbfd 100644
> --- a/lib/libalpm/alpm_list.h
> +++ b/lib/libalpm/alpm_list.h
> @@ -19,23 +19,6 @@
>   */
>  
>  
> -/**
> - * @file alpm_list.h
> - * @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
>  #define ALPM_LIST_H
>  
> @@ -50,7 +33,8 @@ extern "C" {
>  #endif
>  
>  /**
> - * @addtogroup alpm_list List Functions
> + * @ingroup libalpm
> + * @addtogroup libalpm-list libalpm-list(3)
>   * @brief Functions to manipulate alpm_list_t lists.
>   *
>   * These functions are designed to create, destroy, and modify lists of
> @@ -60,7 +44,7 @@ extern "C" {
>   * It is exposed so front ends can use it to prevent the need to reimplement
>   * lists of their own; however, it is not required that the front end uses
>   * it.
> - * @{
> +  * @{
>   */
>  
>  /** A doubly linked list */
>

On 21/12/2020 01:47, Allan McRae wrote:
> There seems to be a lot of duplication from our footer.asciidoc here.  Why?

Just because I don't know how to de duplicate it. Doxygen does not seem
to provide a way to use asciidoc or include a raw footer.

I don't know how else to do about it.