[pacman-dev] [PATCH] Add Doxygen documentation for add.c of libalpm

[Richard Pougnet]

Signed-off-by: Richard Pougnet <richard at pougnet.ca>
---
 lib/libalpm/add.c | 52 +++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 49 insertions(+), 3 deletions(-)

diff --git a/lib/libalpm/add.c b/lib/libalpm/add.c
index 45c57b0..73112fc 100644
--- a/lib/libalpm/add.c
+++ b/lib/libalpm/add.c
@@ -47,7 +47,16 @@
 #include "remove.h"
 #include "handle.h"
 
-/** Add a package to the transaction. */
+/** Adds a package to transaction add list
+ * Finds the target package and compares
+ * to the local version (if it exists).
+ * If version is newer then cache, or downgrade
+ * is desired, the package is then added to the list
+ * and log file is updated.
+ * @param handle the context handle
+ * @param pkg the package to be added
+ * @return 0 on success, 1 on error
+ */
 int SYMEXPORT alpm_add_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg)
 {
 	const char *pkgname, *pkgver;
@@ -104,6 +113,18 @@ int SYMEXPORT alpm_add_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg)
 	return 0;
 }
 
+/** Extracts a package.
+ * Loads the package archive, reads it 
+ * and then extracts.
+ * If non critical error occured, logs and
+ * continues. Else, extract fails.
+ * @param handle the context handle
+ * @param archive the package archive
+ * @param entry the entry to be extracted 
+ * @param filename the filename of the archive
+ * @param origname the name of the package
+ * @return 0 on success, 1 on error
+ */
 static int perform_extraction(alpm_handle_t *handle, struct archive *archive,
 		struct archive_entry *entry, const char *filename, const char *origname)
 {
@@ -129,6 +150,12 @@ static int perform_extraction(alpm_handle_t *handle, struct archive *archive,
 	}
 	return 0;
 }
+/** Attempts to rename an entry
+ * @param handle the context handler
+ * @param src the original name
+ * @param dest the final name 
+ * @return 0 on success, 1 on error
+*/
 
 static int try_rename(alpm_handle_t *handle, const char *src, const char *dest)
 {
@@ -141,7 +168,14 @@ static int try_rename(alpm_handle_t *handle, const char *src, const char *dest)
 	}
 	return 0;
 }
-
+/** Extracts a single file
+ * @param handle the context handler
+ * @param archive the package archive
+ * @param entry the archive entry
+ * @param newpkg the new package
+ * @param oldpkg the old package
+ * @return 0 on success, 1 on error
+*/
 static int extract_single_file(alpm_handle_t *handle, struct archive *archive,
 		struct archive_entry *entry, alpm_pkg_t *newpkg, alpm_pkg_t *oldpkg)
 {
@@ -450,7 +484,15 @@ needbackup_cleanup:
 	free(entryname_orig);
 	return errors;
 }
-
+/** Commits a package to the database
+ * Creates a database entry for a newly installed
+ * package.
+ * @param handle the context handler
+ * @param newpkg the package to be entered
+ * @param pkg_current the current package number
+ * @param pkg_count total number of packages to be committed
+ * @return 0 on success, -1 on error
+*/
 static int commit_single_pkg(alpm_handle_t *handle, alpm_pkg_t *newpkg,
 		size_t pkg_current, size_t pkg_count)
 {
@@ -667,6 +709,10 @@ cleanup:
 	return ret;
 }
 
+/** Upgrades a package
+ * @param handle the context handler
+ * @return 0 on success, -1 on error
+*/
 int _alpm_upgrade_packages(alpm_handle_t *handle)
 {
 	size_t pkg_count, pkg_current;
-- 
1.8.3.4