[pacman-dev] [PATCH 3/4] Clean up doxygen @param warnings.
Jeremy Heiner
scalaprotractor at gmail.com
Sat Dec 21 23:22:25 EST 2013
Because until recently most files were not INPUT to doxygen, the
markup in the unused files was not always modified along with the
code. This commit updates that markup to match the code.
That left a single warning about how alpm.h is #included so many times
that drawing a graph of those #includes resulted in too many nodes.
This is not an interesting warning, so it is filtered from 'make
doxygen-run' (note that the warning still appears in the log file).
Signed-off-by: Jeremy Heiner <ScalaProtractor at gmail.com>
---
doc/Makefile.am | 3 ++-
lib/libalpm/be_local.c | 2 +-
lib/libalpm/be_package.c | 3 ++-
lib/libalpm/deps.c | 4 ++--
lib/libalpm/dload.c | 3 ++-
lib/libalpm/signing.c | 3 +++
lib/libalpm/sync.c | 2 +-
lib/libalpm/util.c | 5 +++--
src/pacman/conf.c | 1 -
src/pacman/package.c | 4 ++--
src/pacman/util.c | 1 -
11 files changed, 18 insertions(+), 13 deletions(-)
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 7f284b8..e7ebf58 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -85,7 +85,8 @@ endif
doxygen-run:
mkdir -p doxyout
doxygen 2>&1 >doxyout/doxygen-run.stdout | \
- tee doxyout/doxygen-run.stderr
+ tee doxyout/doxygen-run.stderr | \
+ fgrep -v "Included by graph for 'alpm.h' not generated" | cat
clean-local: doxygen-clean
doxygen-clean:
diff --git a/lib/libalpm/be_local.c b/lib/libalpm/be_local.c
index 2c18a45..d10109a 100644
--- a/lib/libalpm/be_local.c
+++ b/lib/libalpm/be_local.c
@@ -261,7 +261,7 @@ error:
/**
* Read next entry from a package mtree file.
* @param pkg the package that the mtree file is being read from
- * @param archive the archive structure reading from the mtree file
+ * @param mtree the archive structure reading from the mtree file
* @param entry an archive_entry to store the entry header information
* @return 0 if end of archive is reached, non-zero otherwise.
*/
diff --git a/lib/libalpm/be_package.c b/lib/libalpm/be_package.c
index aaf60fe..7971aa5 100644
--- a/lib/libalpm/be_package.c
+++ b/lib/libalpm/be_package.c
@@ -152,7 +152,8 @@ static struct pkg_operations *get_file_pkg_ops(void)
/**
* Parses the package description file for a package into a alpm_pkg_t struct.
- * @param archive the archive to read from, pointed at the .PKGINFO entry
+ * @param handle the context handle
+ * @param a the archive to read from, pointed at the .PKGINFO entry
* @param newpkg an empty alpm_pkg_t struct to fill with package info
*
* @return 0 on success, -1 on error
diff --git a/lib/libalpm/deps.c b/lib/libalpm/deps.c
index e5a0404..177b417 100644
--- a/lib/libalpm/deps.c
+++ b/lib/libalpm/deps.c
@@ -315,7 +315,7 @@ alpm_pkg_t SYMEXPORT *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstri
* 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 rem 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.
@@ -774,7 +774,7 @@ alpm_pkg_t SYMEXPORT *alpm_find_dbs_satisfier(alpm_handle_t *handle,
* searched first for any dependency packages needed to complete the
* resolve, and to which will be added any [pkg] and all of its
* dependencies not already on the list
- * @param remove is the set of packages which will be removed in this
+ * @param rem is the set of packages which will be removed in this
* transaction
* @param data returns the dependency which could not be satisfied in the
* event of an error
diff --git a/lib/libalpm/dload.c b/lib/libalpm/dload.c
index c74d2ad..2ad6782 100644
--- a/lib/libalpm/dload.c
+++ b/lib/libalpm/dload.c
@@ -615,7 +615,8 @@ cleanup:
* Does not overwrite an existing file if the download fails.
* @param payload the payload context
* @param localpath the directory to save the file in
- * @param final_file the real name of the downloaded file (may be NULL)
+ * @param final_file non-NULL to receive the real name of the downloaded file
+ * @param final_url non-NULL to receive the effective URL
* @return 0 on success, -1 on error (pm_errno is set accordingly if errors_ok == 0)
*/
int _alpm_download(struct dload_payload *payload, const char *localpath,
diff --git a/lib/libalpm/signing.c b/lib/libalpm/signing.c
index b594a9b..b6afef4 100644
--- a/lib/libalpm/signing.c
+++ b/lib/libalpm/signing.c
@@ -959,6 +959,9 @@ int SYMEXPORT alpm_siglist_cleanup(alpm_siglist_t *siglist)
/**
* Extract the Issuer Key ID from a signature
+ * @param handle the context handle
+ * @param identifier a friendly name for the signed resource; usually a
+ * database or package name
* @param sig PGP signature
* @param len length of signature
* @param keys a pointer to storage for key IDs
diff --git a/lib/libalpm/sync.c b/lib/libalpm/sync.c
index e358585..f783d33 100644
--- a/lib/libalpm/sync.c
+++ b/lib/libalpm/sync.c
@@ -769,7 +769,7 @@ static int apply_deltas(alpm_handle_t *handle)
/**
* Prompts to delete the file now that we know it is invalid.
* @param handle the context handle
- * @param filename the absolute path of the file to test
+ * @param filepath the absolute path of the file to test
* @param reason an error code indicating the reason for package invalidity
*
* @return 1 if file was removed, 0 otherwise
diff --git a/lib/libalpm/util.c b/lib/libalpm/util.c
index da7f51f..4d020e3 100644
--- a/lib/libalpm/util.c
+++ b/lib/libalpm/util.c
@@ -61,7 +61,7 @@
* Modifies str to point to the first character after the token if one is
* found, or NULL if one is not.
* @param str string containing delimited tokens to parse
- * @param delim character delimiting tokens in str
+ * @param delims character delimiting tokens in str
* @return pointer to the first token in str if str is not NULL, NULL if
* str is NULL
*/
@@ -448,7 +448,8 @@ ssize_t _alpm_files_in_directory(alpm_handle_t *handle, const char *path,
/** Write formatted message to log.
* @param handle the context handle
- * @param format formatted string to write out
+ * @param prefix the category ("UNKNOWN" used if NULL or "")
+ * @param fmt formatted string to write out
* @param args formatting arguments
* @return 0 or number of characters written on success, vfprintf return value
* on error
diff --git a/src/pacman/conf.c b/src/pacman/conf.c
index cf8a417..605893b 100644
--- a/src/pacman/conf.c
+++ b/src/pacman/conf.c
@@ -838,7 +838,6 @@ static int _parse_repo(const char *key, char *value, const char *file,
* the root config file. Once called, all existing saved config pieces on the
* section struct are freed.
* @param section the current parsed and saved section data
- * @param parse_options whether we are parsing options or repo data
* @return 0 on success, 1 on failure
*/
static int finish_section(struct section_t *section)
diff --git a/src/pacman/package.c b/src/pacman/package.c
index 52219ff..759ddf8 100644
--- a/src/pacman/package.c
+++ b/src/pacman/package.c
@@ -37,7 +37,9 @@
#define CLBUF_SIZE 4096
/** Turn a depends list into a text list.
+ * @param title passed through to list_display
* @param deps a list with items of type alpm_depend_t
+ * @param cols passed through to list_display
*/
static void deplist_display(const char *title,
alpm_list_t *deps, unsigned short cols)
@@ -52,7 +54,6 @@ static void deplist_display(const char *title,
}
/** Turn a optdepends list into a text list.
- * @param optdeps a list with items of type alpm_depend_t
*/
static void optdeplist_display(alpm_pkg_t *pkg, unsigned short cols)
{
@@ -78,7 +79,6 @@ static void optdeplist_display(alpm_pkg_t *pkg, unsigned short cols)
* Extra information entails 'required by' info for sync packages and backup
* files info for local packages.
* @param pkg package to display information for
- * @param from the type of package we are dealing with
* @param extra should we show extra information
*/
void dump_pkg_full(alpm_pkg_t *pkg, int extra)
diff --git a/src/pacman/util.c b/src/pacman/util.c
index 05135d7..1937458 100644
--- a/src/pacman/util.c
+++ b/src/pacman/util.c
@@ -574,7 +574,6 @@ static size_t table_calc_widths(const alpm_list_t *header,
/** Displays the list in table format
*
- * @param title the tables title
* @param header the column headers. column count is determined by the nr
* of headers
* @param rows the rows to display as a list of lists of strings. the outer
--
1.8.5.2
More information about the pacman-dev
mailing list