[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 *alpm_option_get_root(alpm_handle_t *handle);
+/* End of root accessors */
+/** @} */
+
+
+/** @name Accessors to the database path
+ *
+ * The dbpath is where libalpm stores the local db and
+ * downloads sync databases.
+ * @{
+ */
 
-/** Returns the path to the database directory. Read-only. */
+/** Returns the path to the database directory. Read-only.
+ * @param handle the context handle
+ */
 const char *alpm_option_get_dbpath(alpm_handle_t *handle);
+/* End of dbpath accessors */
+/** @} */
+
+
+/** @name Accessors to the lockfile
+ *
+ * The lockfile is used to ensure two instances of libalpm can not write
+ * to the database at the same time. The lock file is created when
+ * committing a transaction and released when the transaction completes.
+ * Or when calling \link alpm_unlock \endlink.
+ * @{
+ */
 
-/** Get the name of the database lock file. Read-only. */
+/** Get the name of the database lock file. Read-only.
+ * This is the name that the lockfile would have. It does not
+ * matter if the lockfile actually exists on disk.
+ * @param handle the context handle
+ */
 const char *alpm_option_get_lockfile(alpm_handle_t *handle);
+/* End of lockfile accessors */
+/** @} */
 
 /** @name Accessors to the list of package cache directories.
+ *
+ * This is where libalpm will store downloaded packages.
  * @{
  */
+
+/** Gets the currently configured cachedirs,
+ * @param handle the context handle
+ * @return a char* list of cache directories
+ */
 alpm_list_t *alpm_option_get_cachedirs(alpm_handle_t *handle);
+
+/** Sets the cachedirs.
+ * @param handle the context handle
+ * @param cachedirs a char* list of cachdirs. The list will be duped and
+ * the original will still need to be freed by the caller.
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_cachedirs(alpm_handle_t *handle, alpm_list_t *cachedirs);
+
+/** Append a cachedir to the configured cachedirs.
+ * @param handle the context handle
+ * @param cachedir the cachedir to add
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_add_cachedir(alpm_handle_t *handle, const char *cachedir);
+
+/** Remove a cachedir from the configured cachedirs.
+ * @param handle the context handle
+ * @param cachedir the cachedir to remove
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_remove_cachedir(alpm_handle_t *handle, const char *cachedir);
+/* End of cachedir accessors */
 /** @} */
 
+
 /** @name Accessors to the list of package hook directories.
+ *
+ * libalpm will search these directories for hooks to run. A hook in
+ * a later directory will override previous hooks if they have the same name.
  * @{
  */
+
+/** Gets the currently configured hookdirs,
+ * @param handle the context handle
+ * @return a char* list of hook directories
+ */
 alpm_list_t *alpm_option_get_hookdirs(alpm_handle_t *handle);
+
+/** Sets the hookdirs.
+ * @param handle the context handle
+ * @param hookdirs a char* list of hookdirs. The list will be duped and
+ * the original will still need to be freed by the caller.
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_hookdirs(alpm_handle_t *handle, alpm_list_t *hookdirs);
+
+/** Append a hookdir to the configured hookdirs.
+ * @param handle the context handle
+ * @param hookdir the hookdir to add
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_add_hookdir(alpm_handle_t *handle, const char *hookdir);
+
+/** Remove a hookdir from the configured hookdirs.
+ * @param handle the context handle
+ * @param hookdir the hookdir to remove
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_remove_hookdir(alpm_handle_t *handle, const char *hookdir);
+/* End of hookdir accessors */
 /** @} */
 
+
+/** @name Accessors to the list of overwritable files.
+ *
+ * Normally libalpm will refuse to install a package that owns files that
+ * are already on disk and not owned by that package.
+ *
+ * If a conflicting file matches a glob in the overwrite_files list, then no
+ * conflict will be raised and libalpm will simply overwrite the file.
+ * @{
+ */
+
+/** Gets the currently configured overwritable files,
+ * @param handle the context handle
+ * @return a char* list of overwritable file globs
+ */
 alpm_list_t *alpm_option_get_overwrite_files(alpm_handle_t *handle);
+
+/** Sets the overwritable files.
+ * @param handle the context handle
+ * @param globs a char* list of overwritable file globs. The list will be duped and
+ * the original will still need to be freed by the caller.
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_overwrite_files(alpm_handle_t *handle, alpm_list_t *globs);
+
+/** Append an overwritable file to the configured overwritable files.
+ * @param handle the context handle
+ * @param glob the file glob to add
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_add_overwrite_file(alpm_handle_t *handle, const char *glob);
+
+/** Remove a file glob from the configured overwritable files globs.
+ * @note The overwritable file list contains a list of globs. The glob to
+ * remove must exactly match the entry to remove. There is no glob expansion.
+ * @param handle the context handle
+ * @param glob the file glob to remove
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_remove_overwrite_file(alpm_handle_t *handle, const char *glob);
+/* End of overwrite accessors */
+/** @} */
+
 
-/** Returns the logfile name. */
+/** @name Accessors to the log file
+ *
+ * This controls where libalpm will save log output to.
+ * @{
+ */
+
+/** Gets the filepath to the currently set logfile.
+ * @param handle the context handle
+ * @return the path to the logfile
+ */
 const char *alpm_option_get_logfile(alpm_handle_t *handle);
-/** Sets the logfile name. */
+
+/** Sets the logfile path.
+ * @param handle the context handle
+ * @param logfile path to the new location of the logfile
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_logfile(alpm_handle_t *handle, const char *logfile);
+/* End of logfile accessors */
+/** @} */
+
+
+/** @name Accessors to the GPG directory
+ *
+ * This controls where libalpm will store GnuPG's files.
+ * @{
+ */
 
-/** Returns the path to libalpm's GnuPG home directory. */
+/** Returns the path to libalpm's GnuPG home directory.
+ * @param handle the context handle
+ * @return the path to libalpms's GnuPG home directory
+ */
 const char *alpm_option_get_gpgdir(alpm_handle_t *handle);
-/** Sets the path to libalpm's GnuPG home directory. */
+
+/** Sets the path to libalpm's GnuPG home directory.
+ * @param handle the context handle
+ * @param gpgdir the gpgdir to set
+ */
 int alpm_option_set_gpgdir(alpm_handle_t *handle, const char *gpgdir);
+/* End of gpdir accessors */
+/** @} */
+
 
-/** Returns whether to use syslog (0 is FALSE, TRUE otherwise). */
+/** @name Accessors for use syslog
+ *
+ * This controls whether libalpm will also use the syslog. Even if this option
+ * is enabled, libalpm will still try to log to its log file.
+ * @{
+ */
+
+/** Returns whether to use syslog (0 is FALSE, TRUE otherwise).
+ * @param handle the context handle
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_get_usesyslog(alpm_handle_t *handle);
-/** Sets whether to use syslog (0 is FALSE, TRUE otherwise). */
+
+/** Sets whether to use syslog (0 is FALSE, TRUE otherwise).
+ * @param handle the context handle 
+ * @param usesyslog whether to use the syslog (0 is FALSE, TRUE otherwise)
+ */
 int alpm_option_set_usesyslog(alpm_handle_t *handle, int usesyslog);
+/* End of usesyslog accessors */
+/** @} */
+
 
 /** @name Accessors to the list of no-upgrade files.
  * These functions modify the list of files which should
  * not be updated by package installation.
  * @{
  */
+
+/** Get the list of no-upgrade files
+ * @param handle the context handle
+ * @return the char* list of no-upgrade files
+ */
 alpm_list_t *alpm_option_get_noupgrades(alpm_handle_t *handle);
+
+/** Add a file to the no-upgrade list
+ * @param handle the context handle
+ * @param path the path to add
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_add_noupgrade(alpm_handle_t *handle, const char *path);
+
+/** Sets the list of no-upgrade files
+ * @param handle the context handle
+ * @param noupgrade a char* list of file to not upgrade.
+ * The list will be duped and the original will still need to be freed by the caller.
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_noupgrades(alpm_handle_t *handle, alpm_list_t *noupgrade);
+
+/** Remove an entry from the no-upgrade list
+ * @param handle the context handle
+ * @param path the path to remove
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_remove_noupgrade(alpm_handle_t *handle, const char *path);
+
+/** Test if a path matches any of the globs in the no-upgrade list
+ * @param handle the context handle
+ * @param path the path to test
+ * @return 0 is the path matches a glob, negative if there is no match and
+ * positive is the  match was inverted
+ */
 int alpm_option_match_noupgrade(alpm_handle_t *handle, const char *path);
+/* End of noupgrade accessors */
 /** @} */
 
+
 /** @name Accessors to the list of no-extract files.
  * These functions modify the list of filenames which should
  * be skipped packages which should
  * not be upgraded by a sysupgrade operation.
  * @{
  */
+
+/** Get the list of no-extract files
+ * @param handle the context handle
+ * @return the char* list of no-extract files
+ */
 alpm_list_t *alpm_option_get_noextracts(alpm_handle_t *handle);
+
+/** Add a file to the no-extract list
+ * @param handle the context handle
+ * @param path the path to add
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_add_noextract(alpm_handle_t *handle, const char *path);
+
+/** Sets the list of no-extract files
+ * @param handle the context handle
+ * @param noextract a char* list of file to not extract.
+ * The list will be duped and the original will still need to be freed by the caller.
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_noextracts(alpm_handle_t *handle, alpm_list_t *noextract);
+
+/** Remove an entry from the no-extract list
+ * @param handle the context handle
+ * @param path the path to remove
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_remove_noextract(alpm_handle_t *handle, const char *path);
+
+/** Test if a path matches any of the globs in the no-extract list
+ * @param handle the context handle
+ * @param path the path to test
+ * @return 0 is the path matches a glob, negative if there is no match and
+ * positive is the  match was inverted
+ */
 int alpm_option_match_noextract(alpm_handle_t *handle, const char *path);
+/* End of noextract accessors */
 /** @} */
 
+
 /** @name Accessors to the list of ignored packages.
  * These functions modify the list of packages that
  * should be ignored by a sysupgrade.
+ *
+ * Entries in this list may be globs and only match the package's
+ * name. Providers are not taken into account.
  * @{
  */
+
+/** Get the list of ignored packages
+ * @param handle the context handle
+ * @return the char* list of ignored packages
+ */
 alpm_list_t *alpm_option_get_ignorepkgs(alpm_handle_t *handle);
+
+/** Add a file to the ignored package list
+ * @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_option_add_ignorepkg(alpm_handle_t *handle, const char *pkg);
+
+/** Sets the list of packages to ignore
+ * @param handle the context handle
+ * @param ignorepkgs a char* list of packages to ignore
+ * The list will be duped and the original will still need to be freed by the caller.
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_ignorepkgs(alpm_handle_t *handle, alpm_list_t *ignorepkgs);
+
+/** Remove an entry from the ignorepkg list
+ * @param handle the context handle
+ * @param pkg the package to remove
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_remove_ignorepkg(alpm_handle_t *handle, const char *pkg);
+/* End of ignorepkg accessors */
 /** @} */
 
+
 /** @name Accessors to the list of ignored groups.
  * These functions modify the list of groups whose packages
  * should be ignored by a sysupgrade.
+ *
+ * Entries in this list may be globs.
  * @{
  */
+
+/** Get the list of ignored groups
+ * @param handle the context handle
+ * @return the char* list of ignored groups
+ */
 alpm_list_t *alpm_option_get_ignoregroups(alpm_handle_t *handle);
+
+/** Add a file to the ignored group list
+ * @param handle the context handle
+ * @param grp the group to add
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_add_ignoregroup(alpm_handle_t *handle, const char *grp);
+
+/** Sets the list of groups to ignore
+ * @param handle the context handle
+ * @param ignoregrps a char* list of groups to ignore
+ * The list will be duped and the original will still need to be freed by the caller.
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_ignoregroups(alpm_handle_t *handle, alpm_list_t *ignoregrps);
+
+/** Remove an entry from the ignoregroup list
+ * @param handle the context handle
+ * @param grp the group to remove
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_remove_ignoregroup(alpm_handle_t *handle, const char *grp);
+/* End of ignoregroup accessors */
 /** @} */
 
+
 /** @name Accessors to the list of ignored dependencies.
  * These functions modify the list of dependencies that
  * should be ignored by a sysupgrade.
+ *
+ * This is effectivley a list of virtual providers that
+ * packages can use to satisfy their dependencies.
  * @{
  */
+
+/** Gets the list of dependencies that are assumed to be met
+ * @param handle the context handle
+ * @return a list of alpm_depend_t*
+ */
 alpm_list_t *alpm_option_get_assumeinstalled(alpm_handle_t *handle);
+
+/** Add a depend to the assumed installed list
+ * @param handle the context handle
+ * @param dep the dependency to add
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_add_assumeinstalled(alpm_handle_t *handle, const alpm_depend_t *dep);
+
+/** Sets the list of dependnecies that are assumed to be met
+ * @param handle the context handle
+ * @param deps a list of *alpm_depend_t
+ * The list will be duped and the original will still need to be freed by the caller.
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_assumeinstalled(alpm_handle_t *handle, alpm_list_t *deps);
+
+/** Remove an entry from the assume installed list
+ * @param handle the context handle
+ * @param dep the dep to remove
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_remove_assumeinstalled(alpm_handle_t *handle, const alpm_depend_t *dep);
+/* End of assunmeinstalled accessors */
 /** @} */
 
-/** Returns the targeted architecture. */
+
+/** @name Accessors for the configured architecture
+ *
+ * libalpm will only install packages that match the configured architecture.
+ * The architecture does not need to match the physical architecture.
+ * It can just be treated as a label.
+ * @{
+ */
+
+/** Returns the allowed package architecture.
+ * @param handle the context handle
+ * @return the configured package architecture
+ */
 const char *alpm_option_get_arch(alpm_handle_t *handle);
-/** Sets the targeted architecture. */
+
+/** Sets the allowed package architecture.
+ * @param handle the context handle
+ * @param arch the architecture to set
+ */
 int alpm_option_set_arch(alpm_handle_t *handle, const char *arch);
+/* End of arch accessors */
+/** @} */
+
+
+/** @name Accessors for check space.
+ *
+ * This controls whether libalpm will check if there is sufficient before
+ * installing packages.
+ * @{
+ */
 
+/** Get whether or not checking for free space before installing packages is enabled.
+ * @param handle the context handle
+ * @return 0 if disabled, 1 if enabled
+ */
 int alpm_option_get_checkspace(alpm_handle_t *handle);
+
+/** Enable/disable checking free space before installing packages.
+ * @param handle the context handle
+ * @param checkspace 0 for disabled, 1 for enabled
+ */
 int alpm_option_set_checkspace(alpm_handle_t *handle, int checkspace);
+/* End of checkspace accessors */
+/** @} */
+
+
+/** @name Accessors for the database extension
+ *
+ * This controls the extension used for sync databases. libalpm will use this
+ * extension to both lookup remote databses and as the name used when opening
+ * reading them.
+ *
+ * This is useful for file databases. Seems as files can increase the size of
+ * a database by quite a lot, a server could hold a database without files under
+ * one extension, and another with files under another extension.
+ *
+ * Which one is downloaded and used then depends on this setting.
+ * @{
+ */
 
+/** Gets the configured database extension.
+ * @param handle the context handle
+ * @return the configured database extension
+ */
 const char *alpm_option_get_dbext(alpm_handle_t *handle);
+
+/** Sets the database extension.
+ * @param handle the context handle
+ * @param dbext the database extension to use
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_dbext(alpm_handle_t *handle, const char *dbext);
+/* End of dbext accessors */
+/** @} */
+
+
+/** @name Accessors for the signature levels
+ * @{
+ */
 
+/** Get the default siglevel.
+ * @param handle the context handle
+ * @return a \link alpm_siglevel_t \endlink bitfield of the siglevel
+ */
 int alpm_option_get_default_siglevel(alpm_handle_t *handle);
+
+/** Set the default siglevel.
+ * @param handle the context handle
+ * @param level a \link alpm_siglevel_t \endlink bitfield of the level to set
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_default_siglevel(alpm_handle_t *handle, int level);
 
+/** Get the configured local file siglevel.
+ * @param handle the context handle
+ * @return a \link alpm_siglevel_t \endlink bitfield of the siglevel
+ */
 int alpm_option_get_local_file_siglevel(alpm_handle_t *handle);
+
+/** Set the local file siglevel.
+ * @param handle the context handle
+ * @param level a \link alpm_siglevel_t \endlink bitfield of the level to set
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_local_file_siglevel(alpm_handle_t *handle, int level);
 
+/** Get the configured remote file siglevel.
+ * @param handle the context handle
+ * @return a \link alpm_siglevel_t \endlink bitfield of the siglevel
+ */
 int alpm_option_get_remote_file_siglevel(alpm_handle_t *handle);
+
+/** Set the remote file siglevel.
+ * @param handle the context handle
+ * @param level a \link alpm_siglevel_t \endlink bitfield of the level to set
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_remote_file_siglevel(alpm_handle_t *handle, int level);
+/* End of signature accessors */
+/** @} */
 
+
+/** @name Accessors for download timeout
+ *
+ * By default, libalpm will timeout if a download has been transferring
+ * less than 1 byte for 10 seconds.
+ * @{
+ */
+
+/** Enables/disables the download timeout.
+ * @param handle the context handle
+ * @param disable_dl_timeout 0 for enabled, 1 for disabled
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_option_set_disable_dl_timeout(alpm_handle_t *handle, unsigned short disable_dl_timeout);
+/* End of disable_dl_timeout accessors */
+/** @} */
+
 
+/** @name Accessors for parallel downloads
+ * \link alpm_db_update \endlink, \link alpm_fetch_pkgurl \endlink and
+ * \link alpm_trans_commit \endlink can all download packages in parallel.
+ * This setting configures how many packages can be downloaded in parallel,
+ *
+ * By default this value is set to 1, meaning packages are downloading
+ * sequentially.
+ *
+ * @{
+ */
+
+/** Gets the number of parallel streams to download database and package files.
+ * @param handle the context handle
+ * @return the number of parallel streams to download database and package files
+ */
 int alpm_option_get_parallel_downloads(alpm_handle_t *handle);
 
 /** Sets number of parallel streams to download database and package files.
- * If the function is not called then the default value of '1' stream
- * (i.e. sequential download) is used.
  * @param handle the context handle
  * @param num_streams number of parallel download streams
  * @return 0 on success, -1 on error
  */
 int alpm_option_set_parallel_downloads(alpm_handle_t *handle, unsigned int num_streams);
+/* End of parallel_downloads accessors */
+/** @} */
 
+
+/* End of alpm_options */
 /** @} */
 
+
 /** @addtogroup alpm_packages Package Functions
  * Functions to manipulate libalpm packages
  * @{
-- 
2.29.2