libdpkg: Add JavaDoc module definitions

Define different modules so that the functions are correctly grouped and
shown in the documentation.

lib/dpkg/ar.h

@@ -30,6 +30,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup ar Ar archive handling
+ * @ingroup dpkg-public
+ * @{
+ */
+
 #define DPKG_AR_MAGIC "!<arch>\n"
 
 void dpkg_ar_normalize_name(struct ar_hdr *arh);
@@ -44,6 +50,8 @@ void dpkg_ar_member_put_mem(const char *ar_name, int ar_fd, const char *name,
                             const void *data, size_t size);
 off_t dpkg_ar_member_get_size(const char *ar_name, struct ar_hdr *arh);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_AR_H */

lib/dpkg/arch.h

@@ -28,6 +28,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup arch Architecture database
+ * @ingroup dpkg-public
+ * @{
+ */
+
 enum dpkg_arch_type {
 	arch_none,
 	arch_empty,
@@ -58,6 +64,8 @@ void dpkg_arch_save_list(void);
 
 void varbuf_add_archqual(struct varbuf *vb, const struct dpkg_arch *arch);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_ARCH_H */

lib/dpkg/atomic-file.h

@@ -27,6 +27,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup atomic-file Atomic file operations
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 enum atomic_file_flags {
 	aff_backup = 01,
 };
@@ -47,6 +53,8 @@ void atomic_file_commit(struct atomic_file *file);
 void atomic_file_remove(struct atomic_file *file);
 void atomic_file_free(struct atomic_file *file);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_ATOMIC_FILE_H */

lib/dpkg/buffer.h

@@ -30,6 +30,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup buffer Buffer I/O
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 #define DPKG_BUFFER_SIZE 4096
 
 #define BUFFER_WRITE_VBUF		1
@@ -90,6 +96,8 @@ off_t buffer_skip_Int(int I, int T, off_t limit, const char *desc_fmt, ...)
 	DPKG_ATTR_PRINTF(4);
 off_t buffer_filter(const void *buf, void *hash, int typeFilter, off_t length);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_BUFFER_H */

lib/dpkg/command.h

@@ -25,6 +25,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup command Command execution
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 /**
  * Describe a command to execute.
  */
@@ -50,6 +56,8 @@ void command_exec(struct command *cmd) DPKG_ATTR_NORET;
 
 void command_shell(const char *cmd, const char *name);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_COMMAND_H */

lib/dpkg/compress.h

@@ -29,6 +29,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup compress Compression
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 enum compressor_type {
 	compressor_type_unknown = -1,
 	compressor_type_none,
@@ -59,6 +65,8 @@ void compress_filter(struct compress_params *params, int fd_in, int fd_out,
                      const char *desc, ...)
                      DPKG_ATTR_PRINTF(4);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_COMPRESS_H */

lib/dpkg/debug.h

@@ -28,6 +28,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup debug Debugging
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 enum debugflags {
 	dbg_general = 01,
 	dbg_scripts = 02,
@@ -49,6 +55,8 @@ void debug_set_mask(int mask);
 bool debug_has_flag(int flag);
 void debug(int flag, const char *fmt, ...) DPKG_ATTR_PRINTF(2);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_DEBUG_H */

lib/dpkg/dir.h

@@ -27,10 +27,18 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup dir Directory handling
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 void dir_sync_path(const char *path);
 void dir_sync_path_parent(const char *path);
 void dir_sync_contents(const char *path);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_DIR_H */

lib/dpkg/dpkg-db.h

@@ -35,6 +35,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup dpkg-db In-core package database management
+ * @ingroup dpkg-public
+ * @{
+ */
+
 enum deptype {
   dep_suggests,
   dep_recommends,
@@ -401,6 +407,8 @@ char *nfstrsave(const char*);
 char *nfstrnsave(const char*, size_t);
 void nffreeall(void);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_DPKG_DB_H */

lib/dpkg/dpkg.h

@@ -32,6 +32,23 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @mainpage libdpkg C API
+ *
+ * This is the documentation for the libdpkg C API. It is divided in an
+ * @ref dpkg-internal "internal API" and a @ref dpkg-public "public API".
+ * Applications closely tied to dpkg can make use of the internal API, the
+ * rest should only assume the availability of the public API.
+ *
+ * Applications need to define the LIBDPKG_VOLATILE_API macro to acknowledge
+ * that the API is to be considered volatile, please read doc/README.api for
+ * more information.
+ *
+ * @defgroup dpkg-internal Internal libdpkg C API
+ *
+ * @defgroup dpkg-public Public libdpkg C API
+ */
+
 #define MAXCONFFILENAME     1000
 #define MAXDIVERTFILENAME   1024
 #define MAXCONTROLFILENAME  100

lib/dpkg/ehandle.h

@@ -30,6 +30,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup ehandle Error context handling
+ * @ingroup dpkg-public
+ * @{
+ */
+
 extern volatile int onerr_abort;
 
 enum {
@@ -70,6 +76,8 @@ void do_internerr(const char *file, int line, const char *fmt, ...)
 	DPKG_ATTR_NORET DPKG_ATTR_PRINTF(3);
 #define internerr(...) do_internerr(__FILE__, __LINE__, __VA_ARGS__)
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_EHANDLE_H */

lib/dpkg/error.h

@@ -25,6 +25,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup dpkg_error Error message reporting
+ * @ingroup dpkg-public
+ * @{
+ */
+
 struct dpkg_error {
 	enum dpkg_msg_type {
 		DPKG_MSG_NONE,
@@ -46,6 +52,8 @@ int dpkg_put_errno(struct dpkg_error *err, const char *fmt, ...)
 
 void dpkg_error_destroy(struct dpkg_error *err);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_ERROR_H */

lib/dpkg/fdio.h

@@ -27,9 +27,17 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup fdio File descriptor I/O
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 ssize_t fd_read(int fd, void *buf, size_t len);
 ssize_t fd_write(int fd, const void *buf, size_t len);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_FDIO_H */

lib/dpkg/file.h

@@ -29,6 +29,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup file File handling
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 struct file_stat {
 	uid_t uid;
 	gid_t gid;
@@ -47,6 +53,8 @@ void file_lock(int *lockfd, enum file_lock_flags flags, const char *filename,
                const char *desc);
 void file_unlock(int fd, const char *desc);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_FILE_H */

lib/dpkg/glob.h

@@ -25,6 +25,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup glob File globbing
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 struct glob_node {
 	struct glob_node *next;
 	char *pattern;
@@ -33,6 +39,8 @@ struct glob_node {
 void glob_list_prepend(struct glob_node **list, char *pattern);
 void glob_list_free(struct glob_node *head);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_GLOB_H */

lib/dpkg/i18n.h

@@ -25,6 +25,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup i18n Internationalization support
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 #include <gettext.h>
 
 /* We need to include this because pgettext() uses LC_MESSAGES, but libintl.h
@@ -36,6 +42,8 @@ DPKG_BEGIN_DECLS
 #define N_(str) gettext_noop(str)
 #define C_(ctxt, str) pgettext(ctxt, str)
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_I18N_H */

lib/dpkg/macros.h

@@ -21,6 +21,12 @@
 #ifndef LIBDPKG_MACROS_H
 #define LIBDPKG_MACROS_H
 
+/**
+ * @defgroup macros C language support macros
+ * @ingroup dpkg-public
+ * @{
+ */
+
 #ifndef LIBDPKG_VOLATILE_API
 #error "The libdpkg API is to be considered volatile, please read 'README.api'."
 #endif
@@ -73,6 +79,11 @@
 #define DPKG_END_DECLS
 #endif
 
+/**
+ * @def array_count
+ *
+ * Returns the amount of items in an array.
+ */
 #ifndef array_count
 #define array_count(a) (sizeof(a) / sizeof((a)[0]))
 #endif
@@ -88,4 +99,6 @@
 #endif
 #endif
 
+/** @} */
+
 #endif /* LIBDPKG_MACROS_H */

lib/dpkg/namevalue.h

@@ -26,6 +26,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup namevalue Name/Value data
+ * @ingroup dpkg-public
+ * @{
+ */
+
 struct namevalue {
 	const char *name;
 	int value;
@@ -40,6 +46,8 @@ struct namevalue {
 const struct namevalue *namevalue_find_by_name(const struct namevalue *head,
                                                const char *str);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_NAMEVALUE_H */

lib/dpkg/options.h

@@ -25,6 +25,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup options Option parsing
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 typedef int action_func(const char *const *argv);
 
 struct cmdinfo {
@@ -70,6 +76,8 @@ void setobsolete(const struct cmdinfo *cip, const char *value);
 #define OBSOLETE(longopt, shortopt) \
  { longopt, shortopt, 0, NULL, NULL, setobsolete, 0, NULL, NULL }
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_OPTIONS_H */

lib/dpkg/parsedump.h

@@ -23,6 +23,12 @@
 #ifndef LIBDPKG_PARSEDUMP_H
 #define LIBDPKG_PARSEDUMP_H
 
+/**
+ * @defgroup parsedump In-core package database parsing and reading
+ * @ingroup dpkg-public
+ * @{
+ */
+
 struct fieldinfo;
 
 /**
@@ -130,4 +136,6 @@ struct nickname {
 
 extern const struct fieldinfo fieldinfos[];
 
+/** @} */
+
 #endif /* LIBDPKG_PARSEDUMP_H */

lib/dpkg/path.h

@@ -27,6 +27,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup path Path handling
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 size_t path_trim_slash_slashdot(char *path);
 const char *path_skip_slash_dotslash(const char *path);
 const char *path_basename(const char *path);
@@ -34,6 +40,8 @@ char *path_quote_filename(char *dst, const char *src, size_t size);
 
 char *path_make_temp_template(const char *suffix);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_PATH_H */

lib/dpkg/pkg-array.h

@@ -26,6 +26,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup pkg-array Package array primitives
+ * @ingroup dpkg-public
+ * @{
+ */
+
 /**
  * Holds an array of pointers to package data.
  */
@@ -38,6 +44,8 @@ void pkg_array_init_from_db(struct pkg_array *a);
 void pkg_array_sort(struct pkg_array *a, pkg_sorter_func *pkg_sort);
 void pkg_array_destroy(struct pkg_array *a);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_PKG_ARRAY_H */

lib/dpkg/pkg-format.h

@@ -26,6 +26,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup pkg-format Package information formatting
+ * @ingroup dpkg-public
+ * @{
+ */
+
 struct pkg_format_node;
 
 struct pkg_format_node *pkg_format_parse(const char *fmt);
@@ -33,6 +39,8 @@ void pkg_format_free(struct pkg_format_node *head);
 void pkg_format_show(const struct pkg_format_node *head,
                      struct pkginfo *pkg, struct pkgbin *pkgbin);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_PKG_FORMAT_H */

lib/dpkg/pkg-list.h

@@ -25,6 +25,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup pkg-list Package linked lists
+ * @ingroup dpkg-public
+ * @{
+ */
+
 struct pkg_list {
 	struct pkg_list *next;
 	struct pkginfo *pkg;
@@ -34,6 +40,8 @@ struct pkg_list *pkg_list_new(struct pkginfo *pkg, struct pkg_list *next);
 void pkg_list_free(struct pkg_list *head);
 void pkg_list_prepend(struct pkg_list **head, struct pkginfo *pkg);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_PKG_LIST_H */

lib/dpkg/pkg-queue.h

@@ -26,6 +26,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup pkg-queue Package queues
+ * @ingroup dpkg-public
+ * @{
+ */
+
 struct pkg_queue {
 	struct pkg_list *head, *tail;
 	int length;
@@ -45,6 +51,8 @@ int pkg_queue_is_empty(struct pkg_queue *queue);
 struct pkg_list *pkg_queue_push(struct pkg_queue *queue, struct pkginfo *pkg);
 struct pkginfo *pkg_queue_pop(struct pkg_queue *queue);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* DPKG_PKG_QUEUE_H */

lib/dpkg/pkg-show.h

@@ -26,6 +26,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup pkg-show Package information display
+ * @ingroup dpkg-public
+ * @{
+ */
+
 int pkg_sorter_by_nonambig_name_arch(const void *a, const void *b);
 
 const char *pkg_summary(const struct pkginfo *pkg, const struct pkgbin *pkgbin,
@@ -34,6 +40,8 @@ int pkg_abbrev_want(const struct pkginfo *pkg);
 int pkg_abbrev_status(const struct pkginfo *pkg);
 int pkg_abbrev_eflag(const struct pkginfo *pkg);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* DPKG_PKG_SHOW_H */

lib/dpkg/pkg-spec.h

@@ -32,6 +32,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup pkg-spec Package specifiers
+ * @ingroup dpkg-public
+ * @{
+ */
+
 struct pkg_spec {
 	char *name;
 	const struct dpkg_arch *arch;
@@ -76,6 +82,8 @@ void pkg_spec_iter_init(struct pkg_spec *ps);
 struct pkginfo *pkg_spec_iter_next_pkg(struct pkg_spec *ps);
 void pkg_spec_iter_destroy(struct pkg_spec *ps);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif

lib/dpkg/pkg.h

@@ -26,6 +26,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup pkg Package handling primitives
+ * @ingroup dpkg-public
+ * @{
+ */
+
 typedef int pkg_sorter_func(const void *a, const void *b);
 
 void pkgset_link_pkg(struct pkgset *set, struct pkginfo *pkg);
@@ -37,6 +43,8 @@ void pkg_reset_eflags(struct pkginfo *pkg);
 void pkg_copy_eflags(struct pkginfo *pkg_dst, struct pkginfo *pkg_src);
 void pkg_set_want(struct pkginfo *pkg, enum pkgwant want);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_PKG_H */

lib/dpkg/progname.h

@@ -25,9 +25,17 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup progname Program name handling
+ * @ingroup dpkg-public
+ * @{
+ */
+
 void dpkg_set_progname(const char *name);
 const char *dpkg_get_progname(void);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif

lib/dpkg/progress.h

@@ -27,6 +27,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup progress Progress reporting
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 struct progress {
 	const char *text;
 
@@ -41,6 +47,8 @@ void progress_init(struct progress *progress, const char *text, int max);
 void progress_step(struct progress *progress);
 void progress_done(struct progress *progress);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif

lib/dpkg/string.h

@@ -25,10 +25,18 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup string String handling
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 char *str_escape_fmt(char *dest, const char *src, size_t n);
 char *str_quote_meta(const char *src);
 char *str_strip_quotes(char *str);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_STRING_H */

lib/dpkg/subproc.h

@@ -27,6 +27,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup subproc Sub-process handling
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 void subproc_signals_setup(const char *name);
 void subproc_signals_cleanup(int argc, void **argv);
 
@@ -39,6 +45,8 @@ int subproc_wait(pid_t pid, const char *desc);
 int subproc_check(int status, const char *desc, int flags);
 int subproc_wait_check(pid_t pid, const char *desc, int flags);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_SUBPROC_H */

lib/dpkg/tarfn.h

@@ -29,6 +29,12 @@
 
 #include <dpkg/file.h>
 
+/**
+ * @defgroup tar Tar archive handling
+ * @ingroup dpkg-public
+ * @{
+ */
+
 #define TARBLKSZ	512
 
 enum tar_format {
@@ -86,4 +92,6 @@ struct tar_operations {
 
 int tar_extractor(void *ctx, const struct tar_operations *ops);
 
+/** @} */
+
 #endif

lib/dpkg/test.h

@@ -31,11 +31,19 @@
 /* Make sure NDEBUG is never defined, as we rely on the assert() macro. */
 #undef NDEBUG
 
+/**
+ * @defgroup dpkg_test Test suite support
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 #define test_pass(a)			assert((a))
 #define test_fail(a)			assert(!(a))
 #define test_str(a, op, b)		assert(strcmp((a), (b)) op 0)
 #define test_mem(a, op, b, size)	assert(memcmp((a), (b), (size)) op 0)
 
+/** @} */
+
 #ifndef TEST_MAIN_PROVIDED
 static void test(void);
 

lib/dpkg/trigdeferred.h

@@ -26,6 +26,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup trigdeferred Trigger deferred file handling
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 enum trigdef_updateflags {
 	tduf_nolockok =           001,
 	tduf_write =              002,
@@ -56,6 +62,8 @@ void trigdef_update_printf(const char *format, ...) DPKG_ATTR_PRINTF(1);
 int trigdef_parse(void);
 void trigdef_process_done(void);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_TRIGDEFERRED_H */

lib/dpkg/triglib.h

@@ -27,6 +27,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup triglib Trigger handling
+ * @ingroup dpkg-internal
+ * @{
+ */
+
 /*
  * Hooks for more sophisticated processing in dpkg proper.
  *
@@ -111,6 +117,8 @@ void trig_parse_ci(const char *file, trig_parse_cicb *interest,
 
 void trig_incorporate(enum modstatdb_rw cstatus);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_TRIGLIB_H */

lib/dpkg/varbuf.h

@@ -29,6 +29,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup varbuf Variable length buffers
+ * @ingroup dpkg-public
+ * @{
+ */
+
 /**
  * varbuf_init must be called exactly once before the use of each varbuf
  * (including before any call to varbuf_destroy), or the variable must be
@@ -82,6 +88,8 @@ int varbuf_printf(struct varbuf *v, const char *fmt, ...) DPKG_ATTR_PRINTF(2);
 int varbuf_vprintf(struct varbuf *v, const char *fmt, va_list va)
 	DPKG_ATTR_VPRINTF(2);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #ifdef __cplusplus

lib/dpkg/version.h

@@ -27,6 +27,12 @@
 
 DPKG_BEGIN_DECLS
 
+/**
+ * @defgroup version Version handling
+ * @ingroup dpkg-public
+ * @{
+ */
+
 struct versionrevision {
 	unsigned long epoch;
 	const char *version;
@@ -36,6 +42,8 @@ struct versionrevision {
 void dpkg_version_blank(struct versionrevision *version);
 bool dpkg_version_is_informative(const struct versionrevision *version);
 
+/** @} */
+
 DPKG_END_DECLS
 
 #endif /* LIBDPKG_VERSION_H */