libmount: cleanup docs

Signed-off-by: Karel Zak <kzak@redhat.com>

14 files changed, 296 insertions, 161 deletions

diff --git a/shlibs/mount/src/cache.c b/shlibs/mount/src/cache.c
index 524979b66..bd6ea3a02 100644
--- a/shlibs/mount/src/cache.c
+++ b/shlibs/mount/src/cache.c
@@ -5,6 +5,16 @@
  * GNU Lesser General Public License.
  */
 
+/**
+ * SECTION: cache
+ * @title: Cache
+ * @short_description: paths and tags (UUID/LABEL) caching
+ *
+ * The cache is a very simple API for work with tags (LABEL, UUID, ...) and
+ * paths. The cache uses libblkid as a backend from TAGs resolution.
+ *
+ * All returned paths are always canonicalized.
+ */
 #include <string.h>
 #include <stdlib.h>
 #include <ctype.h>
@@ -20,7 +30,7 @@
 #include "mountP.h"
 
 /*
- * Canonicalized (resolved) paths cache
+ * Canonicalized (resolved) paths & tags cache
  */
 #define MNT_CACHE_CHUNKSZ	128
 
@@ -55,7 +65,7 @@ struct _mnt_cache {
 /**
  * mnt_new_cache:
  *
- * Returns new mnt_cache instance or NULL in case of ENOMEM error.
+ * Returns: new mnt_cache instance or NULL in case of ENOMEM error.
  */
 mnt_cache *mnt_new_cache(void)
 {
@@ -66,7 +76,7 @@ mnt_cache *mnt_new_cache(void)
  * mnt_free_cache:
  * @cache: pointer to mnt_cache instance
  *
- * Deallocates mnt_cache.
+ * Deallocates the cache.
  */
 void mnt_free_cache(mnt_cache *cache)
 {
@@ -158,9 +168,9 @@ error:
 /**
  * mnt_cache_find_path:
  * @cache: pointer to mnt_cache instance
- * @path: requested "native" (non-canonicalized) path
+ * @path: "native" (non-canonicalized) path
  *
- * Returns cached canonicalized path or NULL.
+ * Returns: cached canonicalized path or NULL.
  */
 const char *mnt_cache_find_path(mnt_cache *cache, const char *path)
 {
@@ -188,7 +198,7 @@ const char *mnt_cache_find_path(mnt_cache *cache, const char *path)
  * @token: tag name
  * @value: tag value
  *
- * Returns cached path or NULL.
+ * Returns: cached path or NULL.
  */
 const char *mnt_cache_find_tag(mnt_cache *cache,
 			const char *token, const char *value)
@@ -223,7 +233,7 @@ const char *mnt_cache_find_tag(mnt_cache *cache,
  *
  * Reads @devname LABEL and UUID to the @cache.
  *
- * Returns: 0 if at least on tag was added, 1 if no tag was added or
+ * Returns: 0 if at least one tag was added, 1 if no tag was added or
  *          -1 in case of error.
  */
 int mnt_cache_read_tags(mnt_cache *cache, const char *devname)
@@ -355,7 +365,7 @@ char *mnt_cache_find_tag_value(mnt_cache *cache,
  * @path: "native" path
  * @cache: cache for results or NULL
  *
- * Returns absolute path or NULL in case of error. The result has to be
+ * Returns: absolute path or NULL in case of error. The result has to be
  * deallocated by free() if @cache is NULL.
  */
 char *mnt_resolve_path(const char *path, mnt_cache *cache)
@@ -401,7 +411,7 @@ error:
  * @value: tag value
  * @cache: for results or NULL
  *
- * Returns device name or NULL in case of error. The result has to be
+ * Returns: device name or NULL in case of error. The result has to be
  * deallocated by free() if @cache is NULL.
  */
 char *mnt_resolve_tag(const char *token, const char *value, mnt_cache *cache)
@@ -439,7 +449,7 @@ error:
  * @spec: path or tag
  * @cache: paths cache
  *
- * Returns canonicalized path or NULL. The result has to be
+ * Returns: canonicalized path or NULL. The result has to be
  * deallocated by free() if @cache is NULL.
  */
 char *mnt_resolve_spec(const char *spec, mnt_cache *cache)
@@ -558,7 +568,7 @@ int main(int argc, char *argv[])
 	struct mtest ts[] = {
 		{ "--resolve-path", test_resolve_path, "  resolve paths from stdin" },
 		{ "--resolve-spec", test_resolve_spec, "  evaluate specs from stdin" },
-		{ "--read-tags", test_read_tags,       "  read devname or TAG stdin" },
+		{ "--read-tags", test_read_tags,       "  read devname or TAG from stdin" },
 		{ NULL }
 	};
 
diff --git a/shlibs/mount/src/fs.c b/shlibs/mount/src/fs.c
index d0fadc985..885a4a2b5 100644
--- a/shlibs/mount/src/fs.c
+++ b/shlibs/mount/src/fs.c
@@ -3,10 +3,14 @@
  *
  * This file may be redistributed under the terms of the
  * GNU Lesser General Public License.
- *
- * The mnt_fs is representation of one line in a fstab / mtab / mountinfo.
  */
 
+/**
+ * SECTION: fs
+ * @title: Filesystem
+ * @short_description: mnt_fs is represents one entry in fstab/mtab/mountinfo
+ *
+ */
 #include <stdio.h>
 #include <string.h>
 #include <stdlib.h>
@@ -20,7 +24,7 @@
 /**
  * mnt_new_fs:
  *
- * Returns newly allocated mnt_file fs.
+ * Returns: newly allocated mnt_file fs.
  */
 mnt_fs *mnt_new_fs(void)
 {
@@ -61,7 +65,7 @@ void mnt_free_fs(mnt_fs *fs)
  * mnt_fs_get_userdata:
  * @fs: mnt_file instance
  *
- * Returns private data set by mnt_fs_set_userdata() or NULL.
+ * Returns: private data set by mnt_fs_set_userdata() or NULL.
  */
 void *mnt_fs_get_userdata(mnt_fs *fs)
 {
@@ -74,7 +78,7 @@ void *mnt_fs_get_userdata(mnt_fs *fs)
  *
  * The "userdata" are library independent data.
  *
- * Returns 0 or -1 in case of error (if @fs is NULL).
+ * Returns: 0 or -1 in case of error (if @fs is NULL).
  */
 int mnt_fs_set_userdata(mnt_fs *fs, void *data)
 {
@@ -89,16 +93,13 @@ int mnt_fs_set_userdata(mnt_fs *fs, void *data)
  * @fs: mnt_file (fstab/mtab/mountinfo) fs
  *
  * The mount "source path" is:
- *	- a directory for 'bind' mounts (in fstab or mtab only)
- *	- a device name for standard mounts
- *	- NULL when path is not set (for example when TAG
- *	  (LABEL/UUID) is defined)
+ * - a directory for 'bind' mounts (in fstab or mtab only)
+ * - a device name for standard mounts
  *
  * See also mnt_fs_get_tag() and mnt_fs_get_source().
  *
- * Returns mount "source" path or NULL in case of error or when the path
+ * Returns: mount source path or NULL in case of error or when the path
  * is not defined.
- *
  */
 const char *mnt_fs_get_srcpath(mnt_fs *fs)
 {
@@ -115,7 +116,7 @@ const char *mnt_fs_get_srcpath(mnt_fs *fs)
 /**
  * @fs: mnt_file (fstab/mtab/mountinfo) fs
  *
- * Returns mount "source". Note that the source could be unparsed TAG
+ * Returns: mount source. Note that the source could be unparsed TAG
  * (LABEL/UUID). See also mnt_fs_get_srcpath() and mnt_fs_get_tag().
  */
 const char *mnt_fs_get_source(mnt_fs *fs)
@@ -150,7 +151,9 @@ int __mnt_fs_set_source(mnt_fs *fs, char *source)
  * @fs: fstab/mtab/mountinfo entry
  * @source: new source
  *
- * Returns 0 on success or -1 in case of error.
+ * This function creates a private copy (strdup()) of @source.
+ *
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_fs_set_source(mnt_fs *fs, const char *source)
 {
@@ -179,14 +182,15 @@ int mnt_fs_set_source(mnt_fs *fs, const char *source)
  *
  * "TAG" is NAME=VALUE (e.g. LABEL=foo)
  *
- * The TAG is the first column in the fstab file. The TAG
- * or "srcpath" has to be always set for all entries.
+ * The TAG is the first column in the fstab file. The TAG or "srcpath" has to
+ * be always set for all entries.
  *
  * See also mnt_fs_get_source().
  *
- * Example:
+ * <informalexample>
+ *   <programlisting>
  *	char *src;
- *	mnt_fs *fs = mnt_file_find_target(mf, "/home");
+ *	mnt_fs *fs = mnt_tab_find_target(tb, "/home", MNT_ITER_FORWARD);
  *
  *	if (!fs)
  *		goto err;
@@ -198,8 +202,10 @@ int mnt_fs_set_source(mnt_fs *fs, const char *source)
  *			printf("%s: %s\n", tag, val);	// LABEL or UUID
  *	} else
  *		printf("device: %s\n", src);		// device or bind path
+ *   </programlisting>
+ * </informalexample>
  *
- * Returns 0 on success or -1 in case that a TAG is not defined.
+ * Returns: 0 on success or -1 in case that a TAG is not defined.
  */
 int mnt_fs_get_tag(mnt_fs *fs, const char **name, const char **value)
 {
@@ -216,7 +222,7 @@ int mnt_fs_get_tag(mnt_fs *fs, const char **name, const char **value)
  * mnt_fs_get_target:
  * @fs: fstab/mtab/mountinfo entry pointer
  *
- * Returns pointer to mountpoint path or NULL
+ * Returns: pointer to mountpoint path or NULL
  */
 const char *mnt_fs_get_target(mnt_fs *fs)
 {
@@ -229,7 +235,9 @@ const char *mnt_fs_get_target(mnt_fs *fs)
  * @fs: fstab/mtab/mountinfo entry
  * @target: mountpoint
  *
- * Returns 0 on success or -1 in case of error.
+ * This function creates a private copy (strdup()) of @target.
+ *
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_fs_set_target(mnt_fs *fs, const char *target)
 {
@@ -253,7 +261,7 @@ int mnt_fs_set_target(mnt_fs *fs, const char *target)
  * mnt_fs_get_fstype:
  * @fs: fstab/mtab/mountinfo entry pointer
  *
- * Returns pointer to filesystem type.
+ * Returns: pointer to filesystem type.
  */
 const char *mnt_fs_get_fstype(mnt_fs *fs)
 {
@@ -287,7 +295,9 @@ int __mnt_fs_set_fstype(mnt_fs *fs, char *fstype)
  * @fs: fstab/mtab/mountinfo entry
  * @fstype: filesystem type
  *
- * Returns 0 on success or -1 in case of error.
+ * This function creates a private copy (strdup()) of @fstype.
+ *
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_fs_set_fstype(mnt_fs *fs, const char *fstype)
 {
@@ -308,7 +318,7 @@ int mnt_fs_set_fstype(mnt_fs *fs, const char *fstype)
  * mnt_fs_get_optstr:
  * @fs: fstab/mtab/mountinfo entry pointer
  *
- * Returns pointer to mount option string with all options (FS and VFS)
+ * Returns: pointer to mount option string with all options (FS and VFS)
  */
 const char *mnt_fs_get_optstr(mnt_fs *fs)
 {
@@ -321,22 +331,30 @@ const char *mnt_fs_get_optstr(mnt_fs *fs)
  * @fs: fstab/mtab/mountinfo entry
  * @optstr: options string
  *
- * Returns 0 on success or -1 in case of error.
+ * This function creates a private copy (strdup()) of @optstr.
+ *
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_fs_set_optstr(mnt_fs *fs, const char *optstr)
 {
+	char *p;
+
 	assert(fs);
 
 	if (!fs || !optstr)
 		return -1;
+	p = strdup(optstr);
+	if (!p)
+		return -1;
+
 	free(fs->optstr);
 	free(fs->fs_optstr);
 	free(fs->vfs_optstr);
 	fs->fs_optstr = fs->vfs_optstr = NULL;
 
-	fs->optstr = strdup(optstr);
+	fs->optstr = p;
 
-	return fs->optstr ? 0 : -1;
+	return 0;
 }
 
 /**
@@ -345,7 +363,7 @@ int mnt_fs_set_optstr(mnt_fs *fs, const char *optstr)
  *
  * This function works for "mountinfo" files only.
  *
- * Returns pointer to superblock (fs-depend) mount option string or NULL.
+ * Returns: pointer to superblock (fs-depend) mount option string or NULL.
  */
 const char *mnt_fs_get_fs_optstr(mnt_fs *fs)
 {
@@ -359,7 +377,7 @@ const char *mnt_fs_get_fs_optstr(mnt_fs *fs)
  *
  * This function works for "mountinfo" files only.
  *
- * Returns pointer to fs-independent (VFS) mount option string or NULL.
+ * Returns: pointer to fs-independent (VFS) mount option string or NULL.
  */
 const char *mnt_fs_get_vfs_optstr(mnt_fs *fs)
 {
@@ -372,7 +390,7 @@ const char *mnt_fs_get_vfs_optstr(mnt_fs *fs)
  * mnt_fs_get_freq:
  * @fs: fstab/mtab/mountinfo entry pointer
  *
- * Returns "dump frequency in days".
+ * Returns: "dump frequency in days".
  */
 int mnt_fs_get_freq(mnt_fs *fs)
 {
@@ -385,7 +403,7 @@ int mnt_fs_get_freq(mnt_fs *fs)
  * @fs: fstab/mtab entry pointer
  * @freq: dump frequency in days
  *
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_fs_set_freq(mnt_fs *fs, int freq)
 {
@@ -400,7 +418,7 @@ int mnt_fs_set_freq(mnt_fs *fs, int freq)
  * mnt_fs_get_passno:
  * @fs: fstab/mtab entry pointer
  *
- * Returns "pass number on parallel fsck".
+ * Returns: "pass number on parallel fsck".
  */
 int mnt_fs_get_passno(mnt_fs *fs)
 {
@@ -413,7 +431,7 @@ int mnt_fs_get_passno(mnt_fs *fs)
  * @fs: fstab/mtab entry pointer
  * @passno: pass number
  *
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_fs_set_passno(mnt_fs *fs, int passno)
 {
@@ -469,7 +487,7 @@ dev_t mnt_fs_get_devno(mnt_fs *fs)
  * @value: returns pointer to the begin of the value (e.g. name=VALUE) or NULL
  * @valsz: returns size of options value or 0
  *
- * Returns 0 on success, 1 when not found the @name or -1 in case of error.
+ * Returns: 0 on success, 1 when not found the @name or -1 in case of error.
  */
 int mnt_fs_get_option(mnt_fs *fs, const char *name,
 		char **value, size_t *valsz)
@@ -491,7 +509,7 @@ int mnt_fs_get_option(mnt_fs *fs, const char *name,
  *
  * The 2nd and 3rd attempts are not performed when @cache is NULL.
  *
- * Returns 1 if @fs target is equal to @target else 0.
+ * Returns: 1 if @fs target is equal to @target else 0.
  */
 int mnt_fs_match_target(mnt_fs *fs, const char *target, mnt_cache *cache)
 {
@@ -533,7 +551,7 @@ int mnt_fs_match_target(mnt_fs *fs, const char *target, mnt_cache *cache)
  * The 2nd, 3rd and 4th attempts are not performed when @cache is NULL. The
  * 2nd and 3rd attempts are not performed if @fs->source is tag.
  *
- * Returns 1 if @fs source is equal to @source else 0.
+ * Returns: 1 if @fs source is equal to @source else 0.
  */
 int mnt_fs_match_source(mnt_fs *fs, const char *source, mnt_cache *cache)
 {
@@ -601,7 +619,7 @@ int mnt_fs_match_source(mnt_fs *fs, const char *source, mnt_cache *cache)
  *
  * For more details see mnt_match_fstype().
  *
- * Returns 1 if @fs type is matching to @types else 0. The function returns
+ * Returns: 1 if @fs type is matching to @types else 0. The function returns
  * 0 when types is NULL.
  */
 int mnt_fs_match_fstype(mnt_fs *fs, const char *types)
@@ -616,7 +634,7 @@ int mnt_fs_match_fstype(mnt_fs *fs, const char *types)
  *
  * For more details see mnt_match_options().
  *
- * Returns 1 if @fs type is matching to @options else 0. The function returns
+ * Returns: 1 if @fs type is matching to @options else 0. The function returns
  * 0 when types is NULL.
  */
 int mnt_fs_match_options(mnt_fs *fs, const char *options)
@@ -662,7 +680,7 @@ static char *mangle(const char *s)
 /**
  * mnt_fprintf_line:
  * @f: FILE
- * @fmt: printf-like format string (see MNT_MFILE_PRINTFMT)
+ * @fmt: printf-like format string (see MNT_TAB_PRINTFMT)
  * @source: (spec) device name or tag=value
  * @target: mountpoint
  * @fstype: filesystem type
@@ -670,7 +688,12 @@ static char *mangle(const char *s)
  * @freq: dump frequency in days
  * @passno: pass number on parallel fsck
  *
- * Returns return value from fprintf().
+ * It's recommended to use this function rather than directly call fprintf() to
+ * write an entry to mtab/fstab. All data in these files has to be properly
+ * formatted (for example space within paths/tags has to be escaped, see
+ * fstab(5) for more details).
+ *
+ * Returns: return value from fprintf().
  */
 int mnt_fprintf_line(	FILE *f,
 			const char *fmt,
@@ -709,9 +732,9 @@ done:
  * mnt_fs_fprintf:
  * @fs: fstab/mtab/mountinfo entry
  * @f: FILE
- * @fmt: printf-like format string (see MNT_MFILE_PRINTFMT)
+ * @fmt: printf-like format string (see MNT_TAB_PRINTFMT)
  *
- * Returns return value from fprintf().
+ * Returns: return value from fprintf().
  */
 int mnt_fs_fprintf(mnt_fs *fs, FILE *f, const char *fmt)
 {
@@ -736,7 +759,7 @@ int mnt_fs_fprintf(mnt_fs *fs, FILE *f, const char *fmt)
  * @fs: fstab/mtab/mountinfo entry
  * @file: output
  *
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_fs_print_debug(mnt_fs *fs, FILE *file)
 {
diff --git a/shlibs/mount/src/init.c b/shlibs/mount/src/init.c
index 544361bc7..68c13f949 100644
--- a/shlibs/mount/src/init.c
+++ b/shlibs/mount/src/init.c
@@ -5,12 +5,28 @@
  * GNU Lesser General Public License.
  */
 
+/**
+ * SECTION: init
+ * @title: Library initialization
+ * @short_description: initialize debuging
+ */
+
 #include <stdlib.h>
 
 #include "mountP.h"
 
 int libmount_debug_mask;
 
+/**
+ * mnt_init_debug:
+ * @mask: debug mask (0xffff to enable full debuging)
+ *
+ * If the @mask is not specified then this function reads
+ * LIBMOUNT_DEBUG environment variable to get the mask.
+ *
+ * Already initialized debugging stuff cannot be changed. It does not
+ * have effect to call this function twice.
+ */
 void mnt_init_debug(int mask)
 {
 	if (libmount_debug_mask & DEBUG_INIT)
diff --git a/shlibs/mount/src/iter.c b/shlibs/mount/src/iter.c
index 4baa7ffb4..5c02c2a78 100644
--- a/shlibs/mount/src/iter.c
+++ b/shlibs/mount/src/iter.c
@@ -4,6 +4,15 @@
  * This file may be redistributed under the terms of the
  * GNU Lesser General Public License.
  */
+
+/**
+ * SECTION: iter
+ * @title: Iterator
+ * @short_description: unified iterator
+ *
+ * The iterator keeps direction and last position for access to the internal
+ * library tables/lists.
+ */
 #include <stdio.h>
 #include <string.h>
 #include <stdlib.h>
@@ -14,7 +23,7 @@
  * mnt_new_iter:
  * @direction: MNT_INTER_{FOR,BACK}WARD direction
  *
- * Returns newly allocated generic libmount iterator.
+ * Returns: newly allocated generic libmount iterator.
  */
 mnt_iter *mnt_new_iter(int direction)
 {
diff --git a/shlibs/mount/src/lock.c b/shlibs/mount/src/lock.c
index 2d2b3c07c..e0b0d0b85 100644
--- a/shlibs/mount/src/lock.c
+++ b/shlibs/mount/src/lock.c
@@ -4,6 +4,16 @@
  * This file may be redistributed under the terms of the
  * GNU Lesser General Public License.
  */
+
+/**
+ * SECTION: lock
+ * @title: Mtab locking
+ * @short_description: locking methods for work with /etc/mtab
+ *
+ * The lock is backwardly compatible with the standard linux /etc/mtab locking.
+ * Note, it's necessary to use the same locking schema in all application that
+ * access the file.
+ */
 #include <string.h>
 #include <stdlib.h>
 #include <sys/types.h>
@@ -39,7 +49,7 @@ struct _mnt_lock {
  * @lockfile: path to lockfile or NULL (default is _PATH_MOUNTED_LOCK)
  * @id: unique linkfile identifier or 0 (default is getpid())
  *
- * Returns newly allocated lock handler or NULL on case of error.
+ * Returns: newly allocated lock handler or NULL on case of error.
  */
 mnt_lock *mnt_new_lock(const char *lockfile, pid_t id)
 {
@@ -79,7 +89,7 @@ void mnt_free_lock(mnt_lock *ml)
  * mnt_lock_get_lockfile:
  * @ml: mnt_lock handler
  *
- * Returns path to lockfile.
+ * Returns: path to lockfile.
  */
 const char *mnt_lock_get_lockfile(mnt_lock *ml)
 {
@@ -94,7 +104,7 @@ const char *mnt_lock_get_lockfile(mnt_lock *ml)
  * mnt_lock_get_linkfile:
  * @ml: mnt_lock handler
  *
- * Returns unique (per process) path to linkfile.
+ * Returns: unique (per process) path to linkfile.
  */
 const char *mnt_lock_get_linkfile(mnt_lock *ml)
 {
@@ -126,7 +136,7 @@ static void mnt_lockalrm_handler(int sig)
  * Waits for F_SETLKW, unfortunately we have to use SIGALRM here to interrupt
  * fcntl() to avoid never ending waiting.
  *
- * Returns 0 on success, 1 on timeout, -errno on error.
+ * Returns: 0 on success, 1 on timeout, -errno on error.
  */
 static int mnt_wait_lock(mnt_lock *ml, struct flock *fl, time_t maxtime)
 {
@@ -189,7 +199,7 @@ static int mnt_wait_lock(mnt_lock *ml, struct flock *fl, time_t maxtime)
  * There was very small number of attempts and extremely long waiting (1s)
  * that is useless on machines with large number of mount processes.
  *
- * Now we wait few thousand microseconds between attempts and we have global
+ * Now we wait few thousand microseconds between attempts and we have a global
  * time limit (30s) rather than limit for number of attempts. The advantage
  * is that this method also counts time which we spend in fcntl(F_SETLKW) and
  * number of attempts is not restricted.
@@ -256,11 +266,13 @@ void mnt_unlock_file(mnt_lock *ml)
  *   1. create linkfile (e.g. /etc/mtab~.<pid>)
  *   2. link linkfile --> lockfile (e.g. /etc/mtab~.<pid> --> /etc/mtab~)
  *
- *   3. a) link() successful: setups F_SETLK lock (see fcnlt(2))
- *      b) link() failed: wait (max 30s) on F_SETLKW lock, goto 2.
+ *   3. a) link() success: setups F_SETLK lock (see fcnlt(2))
+ *      b) link() failed:  wait (max 30s) on F_SETLKW lock, goto 2.
  *
  * Example:
  *
+ * <informalexample>
+ *   <programlisting>
  * mnt_lock *ml;
  *
  * void unlock_fallback(void)
@@ -292,8 +304,10 @@ void mnt_unlock_file(mnt_lock *ml)
  *	ml = NULL;
  *	return 0;
  * }
+ *   </programlisting>
+ * </informalexample>
  *
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_lock_file(mnt_lock *ml)
 {
@@ -497,6 +511,10 @@ int test_lock(struct mtest *ts, int argc, char *argv[])
 	return 0;
 }
 
+/*
+ * Note that this test should be executed from a script that creates many
+ * parallel processes, otherwise this test does not make sense.
+ */
 int main(int argc, char *argv[])
 {
 	struct mtest tss[] = {
diff --git a/shlibs/mount/src/mount.h.in b/shlibs/mount/src/mount.h.in
index eeddc812b..c3100ee07 100644
--- a/shlibs/mount/src/mount.h.in
+++ b/shlibs/mount/src/mount.h.in
@@ -248,7 +248,7 @@ extern int mnt_fs_match_fstype(mnt_fs *fs, const char *types);
 extern int mnt_fs_match_options(mnt_fs *fs, const char *options);
 
 /* mtab/fstab line */
-#define MNT_MFILE_PRINTFMT	"%s %s %s %s %d %d\n"
+#define MNT_TAB_PRINTFMT	"%s %s %s %s %d %d\n"
 
 extern int mnt_fprintf_line(
                         FILE *f,
diff --git a/shlibs/mount/src/optent.c b/shlibs/mount/src/optent.c
index 4bb7db109..749f447c4 100644
--- a/shlibs/mount/src/optent.c
+++ b/shlibs/mount/src/optent.c
@@ -5,6 +5,11 @@
  * GNU Lesser General Public License.
  */
 
+/**
+ * SECTION: optent
+ * @title: Mount option entry
+ * @short_description: the entry keeps one parsed mount option
+ */
 #include <string.h>
 #include <stdlib.h>
 #include <ctype.h>
@@ -174,7 +179,7 @@ err:
  * Parses the first mount option from @optstr and move @optstr pointer
  * to the next option.
  *
- * Returns: new optent (parsed option) or NULL in case of error.
+ * Returns new optent (parsed option) or NULL in case of error.
  */
 mnt_optent *mnt_new_optent_from_optstr(char **optstr,
 			struct mnt_optmap const **maps, int nmaps)
@@ -245,10 +250,7 @@ err:
  * mnt_optent_get_map:
  * @op: pointer to mnt_optent instance
  *
- * Note that the @op has to be associated with any option map (see
- * mnt_optent_assign_map()) or NULL is returned.
- *
- * Returns pointer to the head of the map that is associated with the option or
+ * Returns: pointer to the head of the map that is associated with the option or
  * NULL (for "extra options").
  */
 const struct mnt_optmap *mnt_optent_get_map(mnt_optent *op)
@@ -261,10 +263,7 @@ const struct mnt_optmap *mnt_optent_get_map(mnt_optent *op)
  * mnt_optent_get_map_entry:
  * @op: pointer to mnt_optent instance
  *
- * Note that the @op has to be associated with any option map (see
- * mnt_optent_assign_map()) or NULL is returned.
-
- * Returns pointer to the map entry that describes the option or NULL (for
+ * Returns: pointer to the map entry that describes the option or NULL (for
  * "extra options").
  */
 const struct mnt_optmap *mnt_optent_get_mapent(mnt_optent *op)
@@ -277,10 +276,10 @@ const struct mnt_optmap *mnt_optent_get_mapent(mnt_optent *op)
  * mnt_optent_get_type:
  * @op: mnt_optent instance
  *
- * Note that the @op has to be associated with any option map (see
- * mnt_optent_assign_map()) or the default "%s]" is returned.
+ * Note that the @op has to be associated with any option map
+ * or the default "%s]" is returned.
  *
- * Returns pointer to the begin of type format string or NULL. For example:
+ * Returns: pointer to the begin of type format string or NULL. For example:
  *
  *  "%s"  --> string, required argument (definition in the map is: "foo=%s")
  *  "%s]" --> string, optional argument (definition in the map is: "foo[=%s]")
@@ -302,7 +301,7 @@ const char *mnt_optent_get_type(mnt_optent *op)
  *
  * The function unset (zeroize) the option value if the @data pointer is NULL.
  *
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_optent_set_value(mnt_optent *op, const char *data)
 {
@@ -344,7 +343,7 @@ err:
  * mnt_optent_has_value:
  * @option: pointer to mnt_optent instance
  *
- * Returns 1 if the option has actually set an argument value, or 0.
+ * Returns: 1 if the option has actually set an argument value, or 0.
  */
 int mnt_optent_has_value(mnt_optent *op)
 {
@@ -355,10 +354,10 @@ int mnt_optent_has_value(mnt_optent *op)
  * mnt_optent_require_value:
  * @op: pointer to mnt_optent instance
  *
- * Note that the @op has to be associated with any option map (see
- * mnt_optent_assign_map()) or 0 is returned.
+ * Note that the @op has to be associated with any option map
+ * or 0 is returned.
  *
- * Returns 1 if the option requires an argument (option=<arg>).
+ * Returns: 1 if the option requires an argument (option=<arg>).
  */
 int mnt_optent_require_value(mnt_optent *op)
 {
@@ -369,7 +368,7 @@ int mnt_optent_require_value(mnt_optent *op)
  * mnt_optent_is_inverted:
  * @op: pointer to mnt_optent instance
  *
- * Returns 1 if the option has MNT_INVERT mask or 0.
+ * Returns: 1 if the option has MNT_INVERT mask or 0.
  */
 int mnt_optent_is_inverted(mnt_optent *op)
 {
@@ -400,9 +399,9 @@ static int get_number_base(const char *type)
  * (e.g "123ABC" returns -1).
  *
  * This function also converts {enum0,enumN} type to number 0..N. For more
- * details see info about options maps.
+ * details see info about option maps.
  *
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
  */
 int mnt_optent_strtoul_value(mnt_optent *op, unsigned long int *number)
 {
@@ -456,7 +455,7 @@ err:
  * The whole option value has to be possible to convert to the number
  * (e.g "123ABC" returns -1).
  *
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
  */
 int mnt_optent_strtol_value(mnt_optent *op, long int *number)
 {
@@ -500,7 +499,7 @@ err:
  * The whole option value has to be possible to convert to the number
  * (e.g "123ABC" returns -1).
  *
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
  */
 int mnt_optent_strtoull_value(mnt_optent *op, unsigned long long int *number)
 {
@@ -539,7 +538,7 @@ err:
  *
  * See also mnt_optent_has_value().
  *
- * Returns pointer to value or NULL.
+ * Returns: pointer to value or NULL.
  */
 const char  *mnt_optent_get_value(mnt_optent *op)
 {
@@ -550,7 +549,7 @@ const char  *mnt_optent_get_value(mnt_optent *op)
  * mnt_optent_strlen_value:
  * @op: pointer to mnt_optent instance
  *
- * Returns length of string that is necessary to print option value or -1 in
+ * Returns: length of string that is necessary to print option value or -1 in
  * case of error.
  */
 int mnt_optent_strlen_value(mnt_optent *op)
@@ -570,7 +569,7 @@ int mnt_optent_strlen_value(mnt_optent *op)
  * @str: resulting string
  * @size: size of string
  *
- * Returns number of printed characters or negative number in case of error.
+ * Returns: number of printed characters or negative number in case of error.
  */
 int mnt_optent_snprintf_value(mnt_optent *op, char *str, size_t size)
 {
@@ -590,7 +589,7 @@ int mnt_optent_snprintf_value(mnt_optent *op, char *str, size_t size)
  * mnt_optent_dup_value:
  * @op: pointer to mnt_optent instance
  *
- * Returns duplicate a option value.
+ * Returns: duplicate a option value.
  */
 char *mnt_optent_dup_value(mnt_optent *op)
 {
@@ -605,7 +604,7 @@ char *mnt_optent_dup_value(mnt_optent *op)
  * mnt_optent_get_name:
  * @op: pointer to mnt_optent instance
  *
- * Returns option name or NULL in case of error.
+ * Returns: option name or NULL in case of error.
  */
 const char *mnt_optent_get_name(mnt_optent *op)
 {
@@ -620,7 +619,7 @@ const char *mnt_optent_get_name(mnt_optent *op)
  * The initial value of the option mask is a copy from map->mask.
  * Note that the mask is NOT a mountflag/ID.
  *
- * Returns option mask or 0.
+ * Returns: option mask or 0.
  */
 int mnt_optent_get_mask(mnt_optent *op)
 {
@@ -638,7 +637,7 @@ int mnt_optent_get_mask(mnt_optent *op)
  * "nooption" (e.g. noexec) -- you have to carefully check for MNT_INVERT in
  * the option mask. See mnt_optent_get_flag().
  *
- * Returns option ID/mountflag or 0 for extra options (options with undefined
+ * Returns: option ID/mountflag or 0 for extra options (options with undefined
  * options map).
  */
 int mnt_optent_get_id(mnt_optent *op)
@@ -652,19 +651,22 @@ int mnt_optent_get_id(mnt_optent *op)
  * @op: pointer to mnt_optent instance
  * @flags: resulting flags
  *
- * Adds option ID to @flags or removes option ID from @flags when the option
- * is inverted option (e.g. "norelatime")
+ * Adds option ID to @flags or removes the ID from @flags when the option
+ * is an inverted option (e.g. "norelatime")
  *
- * Example:
+ * <informalexample>
+ *  <programlisting>
  *	int flags = 0;
  *
- *	while(mnt_iterate_options(&itr, opts, map, &op) == 0)
+ *	while(mnt_optls_next_option(&itr, opts, map, &op) == 0)
  *		mnt_optent_get_flag(op, &flags);
  *
  *	if (flags & MS_RELATIME)
  *		printf("relatime is set\n");
+ *  </programlisting>
+ * </informalexample>
  *
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
  */
 int mnt_optent_get_flag(mnt_optent *op, int *flags)
 {
@@ -686,9 +688,9 @@ int mnt_optent_get_flag(mnt_optent *op, int *flags)
  * mnt_optent_is_unknown:
  * @op: pointer to mnt_optent instance
  *
- * The "extra option" is unknown option (undefined in any option map)
+ * The "extra options" are unknown options (undefined in any option map)
  *
- * Return 1 or 0.
+ * Returns: 1 or 0.
  */
 int mnt_optent_is_unknown(mnt_optent *op)
 {
@@ -703,7 +705,7 @@ int mnt_optent_is_unknown(mnt_optent *op)
  *
  * Prints details about the option.
  *
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
  */
 int mnt_optent_print_debug(mnt_optent *op, FILE *file)
 {
diff --git a/shlibs/mount/src/optls.c b/shlibs/mount/src/optls.c
index f819d12bc..f8b73470d 100644
--- a/shlibs/mount/src/optls.c
+++ b/shlibs/mount/src/optls.c
@@ -4,6 +4,16 @@
  * This file may be redistributed under the terms of the
  * GNU Lesser General Public License.
  */
+
+/**
+ * SECTION: optls
+ * @title: Options container
+ * @short_description: high-level API for work with parsed mount options
+ *
+ * The optls container allows to work with parsed mount options and generate
+ * arguments for mount(2) syscall, output to mtab or analyze userspace specific
+ * options.
+ */
 #include <string.h>
 #include <stdlib.h>
 #include <ctype.h>
@@ -52,7 +62,8 @@ void mnt_free_optls(mnt_optls *ls)
  * @map: pointer to the custom map
  *
  * Stores pointer to the custom options map (options description). The map has
- * to be accessible all time when the libmount works with options.
+ * to be accessible all time when the libmount works with options. (The map is
+ * usually a static array.)
  *
  * All already stored unknown mount options are reverified against the new map.
  * Note, it's recommented to add all maps to the @optls container before options
@@ -60,6 +71,8 @@ void mnt_free_optls(mnt_optls *ls)
  *
  * Example (add new options "foo" and "bar=<data>"):
  *
+ * <informalexample>
+ *   <programlisting>
  *     #define MY_MS_FOO   (1 << 1)
  *     #define MY_MS_BAR   (1 << 2)
  *
@@ -71,6 +84,8 @@ void mnt_free_optls(mnt_optls *ls)
  *     };
  *
  *     mnt_optls_add_map(ls, myoptions);
+ *   </programlisting>
+ * </informalexample>
  *
  * Returns: 0 on success, 1 on failed verification, or -1 in case of error.
  */
@@ -108,7 +123,9 @@ int mnt_optls_add_map(mnt_optls *ls, const struct mnt_optmap *map)
  * @ls: pointer to mnt_optls instance
  * @map_id: built-in map id (see mnt_get_builtin_map())
  *
- * Returns 0 on success or -1 in case of error.
+ * Same as mnt_optls_add_map(), but works with libmount built in maps.
+ *
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_optls_add_builtin_map(mnt_optls *ls, int id)
 {
@@ -165,10 +182,10 @@ mnt_optent *mnt_optls_add_option(mnt_optls *ls,
  * @ls: pointer to mnt_optls instance.
  * @optstr: zero terminated string with mount options (comma separaed list)
  *
- * Parses @optstr and all options from @optstr are added to @optls.  It's
+ * Parses @optstr and all options from @optstr are added to the @optls. It's
  * possible to call this function more than once. The new options from @optstr
  * will be appended to the container.
-*
+ *
  * The options are accessible by mnt_optls_next_option().
  *
  * If the @optls container is associated with any options map(s), all new
@@ -183,7 +200,7 @@ mnt_optent *mnt_optls_add_option(mnt_optls *ls,
  *      mnt_optls_add_option(ls, "user", "snake");
  *      mnt_optls_add_option(ls, "noexec", NULL);
  *
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_optls_parse_optstr(mnt_optls *ls, const char *optstr)
 {
@@ -210,7 +227,7 @@ int mnt_optls_parse_optstr(mnt_optls *ls, const char *optstr)
  * @ls: pointer to mnt_optls instance
  * @name: option name
  *
- * Returns 0 on success, 1 if @name not found and -1 in case of error.
+ * Returns: 0 on success, 1 if @name not found and -1 in case of error.
  */
 int mnt_optls_remove_option(mnt_optls *ls, const char *name)
 {
@@ -254,7 +271,7 @@ int mnt_optls_remove_option(mnt_optls *ls, const char *name)
  *
  * See also mnt_optent_get_flag() and mnt_optls_remove_option_by_iflags().
  *
- * Returns number of removed options or -1 in case of error.
+ * Returns: number of removed options or -1 in case of error.
  */
 int mnt_optls_remove_option_by_flags(mnt_optls *ls,
 		const struct mnt_optmap *map, const int flags)
@@ -302,7 +319,7 @@ int mnt_optls_remove_option_by_flags(mnt_optls *ls,
  *
  * See also mnt_optent_get_flag() and mnt_optls_remove_option_by_flags().
  *
- * Returns number of removed options or -1 in case of error.
+ * Returns: number of removed options or -1 in case of error.
  */
 int mnt_optls_remove_option_by_iflags(mnt_optls *ls,
 		const struct mnt_optmap *map, const int flags)
@@ -346,7 +363,8 @@ int mnt_optls_remove_option_by_iflags(mnt_optls *ls,
  * @option: returns pointer to the option object
  *
  * Example (print all options):
- *
+ * <informalexample>
+ *   <programlisting>*
  *     mnt_optent *option;
  *     mnt_optls *ls = mnt_optls_new();
  *
@@ -354,8 +372,10 @@ int mnt_optls_remove_option_by_iflags(mnt_optls *ls,
  *
  *     while(mnt_optls_next_option(ls, itr, NULL, &option))
  *         printf("%s\n", mnt_optent_get_name(option)));
+ *   </programlisting>
+ * </informalexample>
  *
- * Returns 0 on succes, -1 in case of error or 1 at end of list.
+ * Returns: 0 on succes, -1 in case of error or 1 at end of list.
  */
 int mnt_optls_next_option(mnt_optls *ls, mnt_iter *itr,
 		const struct mnt_optmap *map, mnt_optent **option)
@@ -382,7 +402,7 @@ int mnt_optls_next_option(mnt_optls *ls, mnt_iter *itr,
  * @ls: pointer to mnt_optls instance
  * @name: options name
  *
- * Returns the option or NULL.
+ * Returns: the option or NULL.
  */
 mnt_optent *mnt_optls_get_option(mnt_optls *ls, const char *name)
 {
@@ -416,7 +436,7 @@ mnt_optent *mnt_optls_get_option(mnt_optls *ls, const char *name)
  * mnt_optls_create_mountflags() that returns MNT_MFLAG options
  * (mount(2) flags) only.
  *
- * Return IDs from all options.
+ * Return: IDs from all options.
  */
 int mnt_optls_get_ids(mnt_optls *ls, const struct mnt_optmap *map)
 {
@@ -444,7 +464,7 @@ int mnt_optls_get_ids(mnt_optls *ls, const struct mnt_optmap *map)
  * The mountflags are IDs from all MNT_MFLAG options. See "struct mnt_optmap".
  * For more details about mountflags see mount(2) syscall.
  *
- * Returns mount flags or 0.
+ * Returns: mount flags or 0.
  */
 int mnt_optls_create_mountflags(mnt_optls *ls)
 {
@@ -474,7 +494,7 @@ int mnt_optls_create_mountflags(mnt_optls *ls)
  *
  * For more details about mountdata see mount(2) syscall.
  *
- * Returns newly allocated string with mount options or NULL in case of error.
+ * Returns: newly allocated string with mount options or NULL in case of error.
  */
 char *mnt_optls_create_mountdata(mnt_optls *ls)
 {
@@ -510,7 +530,7 @@ err:
  * mnt_optls_create_mtab_optstr:
  * @ls: pointer to mnt_optls instance
  *
- * Returns newly allocated string with mount options for mtab.
+ * Returns: newly allocated string with mount options for mtab.
  */
 char *mnt_optls_create_mtab_optstr(mnt_optls *ls)
 {
@@ -547,8 +567,8 @@ err:
  * mnt_optls_create_userspace_optstr:
  * @ls: pointer to mnt_optls instance
  *
- * Returns newly allocated string with mount options that are
- * userspace specific (e.g. uhelper=).
+ * Returns: newly allocated string with mount options that are
+ * userspace specific (e.g. uhelper=,loop=).
  */
 char *mnt_optls_create_userspace_optstr(mnt_optls *ls)
 {
@@ -589,6 +609,8 @@ err:
  * @ls: pointer to mnt_optls instance
  *
  * Prints details about options container.
+ *
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_optls_print_debug(mnt_optls *ls, FILE *file)
 {
diff --git a/shlibs/mount/src/optmap.c b/shlibs/mount/src/optmap.c
index 873c545ce..ff8cc8c68 100644
--- a/shlibs/mount/src/optmap.c
+++ b/shlibs/mount/src/optmap.c
@@ -3,9 +3,13 @@
  *
  * This file may be redistributed under the terms of the
  * GNU Lesser General Public License.
+ */
+
+/**
+ * SECTION: optmap
+ * @title: Option maps
+ * @short_description: description for mount options
  *
- * Option-maps
- * -----------
  * The mount(2) linux syscall uses two arguments for mount options:
  *
  *    1) mountflags (see MS_* macros in linux/fs.h)
@@ -45,6 +49,8 @@
  *    - MNT_LINUX_MAP     -- fs-independent kernel mount options (usually MS_* flags)
  *    - MNT_USERSPACE_MAP -- userspace specific mount options (e.g. "user", "loop")
  *
+ * For more details about option map struct see "struct mnt_optmap" in
+ * mount/mount.h.
  */
 #include <string.h>
 #include <stdlib.h>
@@ -153,7 +159,7 @@ static const struct mnt_optmap userspace_opts_map[] =
  * MNT_USERSPACE_MAP - userpace mount(8) specific mount options
  *                     (e.g user=, _netdev, ...)
  *
- * Returns internal (static) libmount map.
+ * Returns: static built-in libmount map.
  */
 const struct mnt_optmap *mnt_get_builtin_optmap(int id)
 {
diff --git a/shlibs/mount/src/optstr.c b/shlibs/mount/src/optstr.c
index 3e4eb482d..ed40cacec 100644
--- a/shlibs/mount/src/optstr.c
+++ b/shlibs/mount/src/optstr.c
@@ -5,6 +5,16 @@
  * GNU Lesser General Public License.
  */
 
+/**
+ * SECTION: optstr
+ * @title: Mount oprions string
+ * @short_description: low-level API for work with mount options
+ *
+ * This is simple and low-level API to work with mount options that are stored
+ * in string. This API is independent on the high-level options container and
+ * option maps.
+ */
+
 #include <string.h>
 #include <stdlib.h>
 #include <ctype.h>
@@ -129,7 +139,7 @@ static int mnt_optstr_locate_option(char *optstr, const char *name, char **begin
  *
  * Parses the first option in @optstr  or -1 in case of error.
  *
- * Returns 0 on success, 1 at the end of @optstr or -1 in case of error.
+ * Returns: 0 on success, 1 at the end of @optstr or -1 in case of error.
  */
 int mnt_optstr_next_option(char **optstr, char **name, size_t *namesz,
 					char **value, size_t *valuesz)
diff --git a/shlibs/mount/src/tab.c b/shlibs/mount/src/tab.c
index 819b11d32..71aa805b4 100644
--- a/shlibs/mount/src/tab.c
+++ b/shlibs/mount/src/tab.c
@@ -1,31 +1,37 @@
 /*
- * Copyright (C) 2008 Karel Zak <kzak@redhat.com>
+ * Copyright (C) 2008-2010 Karel Zak <kzak@redhat.com>
  *
  * This file may be redistributed under the terms of the
  * GNU Lesser General Public License.
+ */
+
+/**
+ * SECTION: tab
+ * @title: Filesystems container
+ * @short_description: container for entries from fstab/mtab/mountinfo
+ *
  *
- * Note:
- *	mnt_tab_find_* functions are mount(8) compatible. It means it tries
- *	to found an entry in more iterations where the first attempt is always
- *	based on comparison with unmodified (non-canonicalized or un-evaluated)
- *	paths or tags. For example fstab with two entries:
+ * Note that mnt_tab_find_* functions are mount(8) compatible. These functions
+ * try to found an entry in more iterations where the first attempt is always
+ * based on comparison with unmodified (non-canonicalized or un-evaluated)
+ * paths or tags. For example fstab with two entries:
  *
- *		LABEL=foo	/foo	auto   rw
- *		/dev/foo	/foo	auto   rw
+ *	LABEL=foo	/foo	auto   rw
+ *	/dev/foo	/foo	auto   rw
  *
- *	where both lines are used for the *same* device, then
+ * where both lines are used for the *same* device, then
  *
- *		mnt_tab_find_source(tb, "/dev/foo", &fs);
+ *	mnt_tab_find_source(tb, "/dev/foo", &fs);
  *
- *	will returns the second line, and
+ * will returns the second line, and
  *
- *		mnt_tab_find_source(tb, "LABEL=foo", &fs);
+ *	mnt_tab_find_source(tb, "LABEL=foo", &fs);
  *
- *	will returns the first entry, and
+ * will returns the first entry, and
  *
  *		mnt_tab_find_source(tb, "UUID=<anyuuid>", &fs);
  *
- *	will returns the first entry (if UUID matches with the device).
+ * will returns the first entry (if UUID matches with the device).
  */
 
 #include <string.h>
@@ -51,7 +57,7 @@
  * Note that this function does not parse the file. See also
  * mnt_tab_parse_file().
  *
- * Returns newly allocated tab struct.
+ * Returns: newly allocated tab struct.
  */
 mnt_tab *mnt_new_tab(const char *filename)
 {
@@ -97,7 +103,7 @@ void mnt_free_tab(mnt_tab *tb)
  * mnt_tab_get_nents:
  * @tb: pointer to tab
  *
- * Returns number of valid entries in tab.
+ * Returns: number of valid entries in tab.
  */
 int mnt_tab_get_nents(mnt_tab *tb)
 {
@@ -119,7 +125,7 @@ int mnt_tab_get_nents(mnt_tab *tb)
  *
  * See also mnt_new_cache().
  *
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_tab_set_cache(mnt_tab *tb, mnt_cache *mpc)
 {
@@ -134,7 +140,7 @@ int mnt_tab_set_cache(mnt_tab *tb, mnt_cache *mpc)
  * mnt_tab_get_cache:
  * @tb: pointer to tab
  *
- * Returns pointer to mnt_cache instance or NULL.
+ * Returns: pointer to mnt_cache instance or NULL.
  */
 mnt_cache *mnt_tab_get_cache(mnt_tab *tb)
 {
@@ -146,7 +152,7 @@ mnt_cache *mnt_tab_get_cache(mnt_tab *tb)
  * mnt_tab_get_name:
  * @tb: tab pointer
  *
- * Returns tab filename or NULL.
+ * Returns: tab filename or NULL.
  */
 const char *mnt_tab_get_name(mnt_tab *tb)
 {
@@ -161,7 +167,7 @@ const char *mnt_tab_get_name(mnt_tab *tb)
  *
  * Adds a new entry to tab.
  *
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_tab_add_fs(mnt_tab *tb, mnt_fs *fs)
 {
@@ -190,7 +196,7 @@ int mnt_tab_add_fs(mnt_tab *tb, mnt_fs *fs)
  * @tb: tab pointer
  * @fs: new entry
  *
- * Returns 0 on success or -1 in case of error.
+ * Returns: 0 on success or -1 in case of error.
  */
 int mnt_tab_remove_fs(mnt_tab *tb, mnt_fs *fs)
 {
@@ -255,7 +261,7 @@ int mnt_tab_get_root_fs(mnt_tab *tb, mnt_fs **root)
  * Note that filesystems are returned in the order how was mounted (according to
  * IDs in /proc/self/mountinfo).
  *
- * Returns 0 on success, -1 in case of error or 1 at end of list.
+ * Returns: 0 on success, -1 in case of error or 1 at end of list.
  */
 int mnt_tab_next_child_fs(mnt_tab *tb, mnt_iter *itr,
 			mnt_fs *parent, mnt_fs **chld)
@@ -313,7 +319,7 @@ int mnt_tab_next_child_fs(mnt_tab *tb, mnt_iter *itr,
  * @itr: iterator
  * @fs: returns the next tab entry
  *
- * Returns 0 on success, -1 in case of error or 1 at end of list.
+ * Returns: 0 on success, -1 in case of error or 1 at end of list.
  *
  * Example (list all mountpoints from fstab in backward order):
  *
@@ -364,7 +370,7 @@ again:
  *
  * This function allows search in @tb.
  *
- * Returns -1 in case of error, 1 at end of table or 0 o success.
+ * Returns: -1 in case of error, 1 at end of table or 0 o success.
  */
 int mnt_tab_find_next_fs(mnt_tab *tb, mnt_iter *itr,
 		int (*match_func)(mnt_fs *, void *), void *userdata,
@@ -403,7 +409,7 @@ int mnt_tab_find_next_fs(mnt_tab *tb, mnt_iter *itr,
  *
  * Sets @iter to the position of @fs in the file @tb.
  *
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
  */
 int mnt_tab_set_iter(mnt_tab *tb, mnt_iter *itr, mnt_fs *fs)
 {
@@ -431,7 +437,7 @@ int mnt_tab_set_iter(mnt_tab *tb, mnt_iter *itr, mnt_fs *fs)
  * against realpath(fs->target). The 2nd and 3rd iterations are not performed
  * when @tb cache is not set (see mnt_tab_set_cache()).
  *
- * Returns a tab entry or NULL.
+ * Returns: a tab entry or NULL.
  */
 mnt_fs *mnt_tab_find_target(mnt_tab *tb, const char *path, int direction)
 {
@@ -487,7 +493,7 @@ mnt_fs *mnt_tab_find_target(mnt_tab *tb, const char *path, int direction)
  * The 2nd, 3rd and 4th iterations are not performed when @tb cache is not
  * set (see mnt_tab_set_cache()).
  *
- * Returns a tab entry or NULL.
+ * Returns: a tab entry or NULL.
  */
 mnt_fs *mnt_tab_find_srcpath(mnt_tab *tb, const char *path, int direction)
 {
@@ -587,7 +593,7 @@ mnt_fs *mnt_tab_find_srcpath(mnt_tab *tb, const char *path, int direction)
  * name) and mnt_tab_find_srcpath() is preformed. The second attempt is not
  * performed when @tb cache is not set (see mnt_tab_set_cache()).
 
- * Returns a tab entry or NULL.
+ * Returns: a tab entry or NULL.
  */
 mnt_fs *mnt_tab_find_tag(mnt_tab *tb, const char *tag,
 			const char *val, int direction)
@@ -632,7 +638,7 @@ mnt_fs *mnt_tab_find_tag(mnt_tab *tb, const char *tag,
  * about @source format (device, LABEL, UUID, ...). This function parses @source
  * and calls mnt_tab_find_tag() or mnt_tab_find_srcpath().
  *
- * Returns a tab entry or NULL.
+ * Returns: a tab entry or NULL.
  */
 mnt_fs *mnt_tab_find_source(mnt_tab *tb, const char *source, int direction)
 {
@@ -670,7 +676,7 @@ mnt_fs *mnt_tab_find_source(mnt_tab *tb, const char *source, int direction)
  * @fmt: per line printf-like format string (see MNT_MFILE_PRINTFMT)
  * @tb: tab pointer
  *
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
  */
 int mnt_tab_fprintf(mnt_tab *tb, FILE *f, const char *fmt)
 {
@@ -699,7 +705,7 @@ int mnt_tab_fprintf(mnt_tab *tb, FILE *f, const char *fmt)
  *
  * Writes tab to disk. Don't forget to lock the file (see mnt_lock()).
  *
- * Returns 0 on success, -1 in case of error.
+ * Returns: 0 on success, -1 in case of error.
  */
 int mnt_tab_update_file(mnt_tab *tb)
 {
diff --git a/shlibs/mount/src/tab_parse.c b/shlibs/mount/src/tab_parse.c
index f8d6680fd..fe2b11037 100644
--- a/shlibs/mount/src/tab_parse.c
+++ b/shlibs/mount/src/tab_parse.c
@@ -381,12 +381,8 @@ err:
  *
  * Parses whole table (e.g. /etc/fstab).
  *
- * Returns 0 on success and -1 in case of error. The parse errors is possible
- * to detect by mnt_tab_get_nerrs() and error message is possible to create by
- * mnt_tab_strerror().
- *
- * Example:
- *
+ * <informalexample>
+ *   <programlisting>
  *	mnt_tab *tb = mnt_new_tab("/etc/fstab");
  *	int rc;
  *
@@ -401,6 +397,12 @@ err:
  *		mnt_fprintf_tab(tb, stdout, NULL);
  *
  *	mnt_free_tab(tb);
+ *   </programlisting>
+ * </informalexample>
+ *
+ * Returns: 0 on success and -1 in case of error. The parse errors is possible
+ * to detect by mnt_tab_get_nerrs() and error message is possible to create by
+ * mnt_tab_strerror().
  */
 int mnt_tab_parse_file(mnt_tab *tb)
 {
@@ -450,7 +452,7 @@ error:
  * not provide details (by mnt_tab_strerror()) about failed parsing -- so you
  * should not to use this function for user-writeable files like /etc/fstab.
  *
- * Returns newly allocated tab on success and NULL in case of error.
+ * Returns: newly allocated tab on success and NULL in case of error.
  */
 mnt_tab *mnt_new_tab_from_file(const char *filename)
 {
@@ -472,7 +474,7 @@ mnt_tab *mnt_new_tab_from_file(const char *filename)
  * mnt_tab_get_nerrs:
  * @tb: pointer to table
  *
- * Returns number of broken (parse error) entries in the table.
+ * Returns: number of broken (parse error) entries in the table.
  */
 int mnt_tab_get_nerrs(mnt_tab *tb)
 {
@@ -486,7 +488,7 @@ int mnt_tab_get_nerrs(mnt_tab *tb)
  * @buf: buffer to return error message
  * @buflen: lenght of the buf
  *
- * Returns error message for table (file) parse errors. For example:
+ * Returns: error message for table (file) parse errors. For example:
  *
  *	"/etc/fstab: parse error at line(s): 1, 2 and 3."
  */
diff --git a/shlibs/mount/src/utils.c b/shlibs/mount/src/utils.c
index fb9ffe8d5..1f3337f24 100644
--- a/shlibs/mount/src/utils.c
+++ b/shlibs/mount/src/utils.c
@@ -5,6 +5,11 @@
  * GNU Lesser General Public License.
  */
 
+/**
+ * SECTION: utils
+ * @title: Utils
+ * @short_description: misc utils.
+ */
 #include <unistd.h>
 #include <errno.h>
 #include <stdlib.h>
diff --git a/shlibs/mount/src/version.c b/shlibs/mount/src/version.c
index 0380e1c28..d00a16866 100644
--- a/shlibs/mount/src/version.c
+++ b/shlibs/mount/src/version.c
@@ -7,6 +7,12 @@
  * See COPYING.libmount for the License of this software.
  */
 
+/**
+ * SECTION: version
+ * @title: Version functions
+ * @short_description: functions to get library version.
+ */
+
 #include <unistd.h>
 #include <string.h>
 #include <stdio.h>