libmount: add docs

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

9 files changed, 107 insertions, 72 deletions

diff --git a/shlibs/mount/src/fs.c b/shlibs/mount/src/fs.c
index 885a4a2b5..56a3b977a 100644
--- a/shlibs/mount/src/fs.c
+++ b/shlibs/mount/src/fs.c
@@ -8,7 +8,7 @@
 /**
  * SECTION: fs
  * @title: Filesystem
- * @short_description: mnt_fs is represents one entry in fstab/mtab/mountinfo
+ * @short_description: mnt_fs represents one entry in fstab/mtab/mountinfo
  *
  */
 #include <stdio.h>
@@ -114,6 +114,7 @@ const char *mnt_fs_get_srcpath(mnt_fs *fs)
 }
 
 /**
+ * mnt_fs_get_source:
  * @fs: mnt_file (fstab/mtab/mountinfo) fs
  *
  * Returns: mount source. Note that the source could be unparsed TAG
@@ -390,7 +391,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)
 {
diff --git a/shlibs/mount/src/lock.c b/shlibs/mount/src/lock.c
index e0b0d0b85..2d1f30f4a 100644
--- a/shlibs/mount/src/lock.c
+++ b/shlibs/mount/src/lock.c
@@ -263,8 +263,8 @@ void mnt_unlock_file(mnt_lock *ml)
  *
  * Locking scheme:
  *
- *   1. create linkfile (e.g. /etc/mtab~.<pid>)
- *   2. link linkfile --> lockfile (e.g. /etc/mtab~.<pid> --> /etc/mtab~)
+ *   1. create linkfile (e.g. /etc/mtab~.$PID)
+ *   2. link linkfile --> lockfile (e.g. /etc/mtab~.$PID --> /etc/mtab~)
  *
  *   3. a) link() success: setups F_SETLK lock (see fcnlt(2))
  *      b) link() failed:  wait (max 30s) on F_SETLKW lock, goto 2.
@@ -273,37 +273,37 @@ void mnt_unlock_file(mnt_lock *ml)
  *
  * <informalexample>
  *   <programlisting>
- * mnt_lock *ml;
+ *	mnt_lock *ml;
  *
- * void unlock_fallback(void)
- * {
- *	if (!ml)
- *		return;
- *	mnt_unlock_file(ml);
- *	mnt_free_lock(ml);
- * }
+ *	void unlock_fallback(void)
+ *	{
+ *		if (!ml)
+ *			return;
+ *		mnt_unlock_file(ml);
+ *		mnt_free_lock(ml);
+ *	}
  *
- * int update_mtab()
- * {
- *	int sig = 0;
+ *	int update_mtab()
+ *	{
+ *		int sig = 0;
  *
- *	atexit(unlock_fallback);
+ *		atexit(unlock_fallback);
  *
- *	ml = mnt_new_lock(NULL, 0);
+ *		ml = mnt_new_lock(NULL, 0);
  *
- *	if (mnt_lock_file(ml) != 0) {
- *		printf(stderr, "cannot create %s lockfile\n",
- *				mnt_lock_get_lockfile(ml));
- *		return -1;
- *	}
+ *		if (mnt_lock_file(ml) != 0) {
+ *			printf(stderr, "cannot create %s lockfile\n",
+ *					mnt_lock_get_lockfile(ml));
+ *			return -1;
+ *		}
  *
- *	... modify mtab ...
+ *		... modify mtab ...
  *
- *	mnt_unlock_file(ml);
- *	mnt_free_lock(ml);
- *	ml = NULL;
- *	return 0;
- * }
+ *		mnt_unlock_file(ml);
+ *		mnt_free_lock(ml);
+ *		ml = NULL;
+ *		return 0;
+ *	}
  *   </programlisting>
  * </informalexample>
  *
diff --git a/shlibs/mount/src/mount.h.in b/shlibs/mount/src/mount.h.in
index c3100ee07..409af06a8 100644
--- a/shlibs/mount/src/mount.h.in
+++ b/shlibs/mount/src/mount.h.in
@@ -66,12 +66,9 @@ typedef struct _mnt_optls mnt_optls;
 typedef struct _mnt_optent mnt_optent;
 
 /**
- * struct mnt_optmap:
+ * mnt_optmap:
  *
  * Mount options description (map)
- *
- * The libmount supports mount options with values in %<type>:
- * %s, %d, %u, %o, %x
  */
 struct mnt_optmap
 {
diff --git a/shlibs/mount/src/optent.c b/shlibs/mount/src/optent.c
index 749f447c4..4b35b2d5f 100644
--- a/shlibs/mount/src/optent.c
+++ b/shlibs/mount/src/optent.c
@@ -7,8 +7,8 @@
 
 /**
  * SECTION: optent
- * @title: Mount option entry
- * @short_description: the entry keeps one parsed mount option
+ * @title: Parsed option
+ * @short_description: the mnt_optent keeps one parsed mount option
  */
 #include <string.h>
 #include <stdlib.h>
@@ -357,7 +357,7 @@ int mnt_optent_has_value(mnt_optent *op)
  * 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)
 {
@@ -534,13 +534,12 @@ err:
 /**
  * mnt_optent_get_value:
  * @op: pointer to mnt_optent instance
- * @data: resulting string
  *
  * See also mnt_optent_has_value().
  *
  * Returns: pointer to value or NULL.
  */
-const char  *mnt_optent_get_value(mnt_optent *op)
+const char *mnt_optent_get_value(mnt_optent *op)
 {
 	return op? op->value : NULL;
 }
diff --git a/shlibs/mount/src/optls.c b/shlibs/mount/src/optls.c
index f8b73470d..ff2b912bd 100644
--- a/shlibs/mount/src/optls.c
+++ b/shlibs/mount/src/optls.c
@@ -69,7 +69,7 @@ void mnt_free_optls(mnt_optls *ls)
  * Note, it's recommented to add all maps to the @optls container before options
  * parsing.
  *
- * Example (add new options "foo" and "bar=<data>"):
+ * Example (add new options "foo" and "bar=data"):
  *
  * <informalexample>
  *   <programlisting>
@@ -121,7 +121,7 @@ int mnt_optls_add_map(mnt_optls *ls, const struct mnt_optmap *map)
 /**
  * mnt_optls_add_builtin_map:
  * @ls: pointer to mnt_optls instance
- * @map_id: built-in map id (see mnt_get_builtin_map())
+ * @id: built-in map id (see mnt_get_builtin_map())
  *
  * Same as mnt_optls_add_map(), but works with libmount built in maps.
  *
@@ -436,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.
+ * Returns: IDs from all options.
  */
 int mnt_optls_get_ids(mnt_optls *ls, const struct mnt_optmap *map)
 {
diff --git a/shlibs/mount/src/optmap.c b/shlibs/mount/src/optmap.c
index ff8cc8c68..6eef332c7 100644
--- a/shlibs/mount/src/optmap.c
+++ b/shlibs/mount/src/optmap.c
@@ -12,8 +12,9 @@
  *
  * The mount(2) linux syscall uses two arguments for mount options:
  *
- *    1) mountflags (see MS_* macros in linux/fs.h)
- *    2) mountdata  (usully a comma separated string of options)
+ *	@mountflags: (see MS_* macros in linux/fs.h)
+ *
+ *	@mountdata: (usully a comma separated string of options)
  *
  * The libmount uses options-map(s) to describe mount options. The number of
  * maps is unlimited. The libmount options parser could be easily extended
@@ -21,16 +22,19 @@
  *
  * The option description (map entry) includes:
  *
- *    - option name and argument type (e.g. "loop[=%s]")
- *    - option ID (in the map unique identifier or a mountflags, e.g MS_RDONLY)
- *    - mask (MNT_INVERT, MNT_MDATA, MNT_MFLAG, MNT_NOMTAB)
+ *	@name: and argument type (e.g. "loop[=%s]")
+ *
+ *	@id: (in the map unique identifier or a mountflags, e.g MS_RDONLY)
+ *
+ *	@mask: (MNT_INVERT, MNT_MDATA, MNT_MFLAG, MNT_NOMTAB)
  *
  * The option argument type is defined by:
  *
- *     "=<type>"          -- required argument
- *     "[=<type>]"        -- optional argument
+ *	"=type"   -- required argument
+ *
+ *	"[=type]" -- optional argument
  *
- * where the <type> is sscanf() format string or
+ * where the 'type' is sscanf() format string or
  *
  *     {item0,item1,...}  -- enum (mnt_option_get_number() converts the value
  *                           to 0..N number)
@@ -39,15 +43,32 @@
  * stores the option argument as a string. The conversion to the data type is
  * on-demant by mnt_option_get_value_*() functions.
  *
- * The library checks options argument according to <type> format for simple
+ * The library checks options argument according to 'type' format for simple
  * formats only:
  *
  *	%s, %d, %ld, %lld, %u, %lu, %llu, %x, %o and {enum}
  *
+ * Example:
+ *
+ * <informalexample>
+ *   <programlisting>
+ *     #define MY_MS_FOO   (1 << 1)
+ *     #define MY_MS_BAR   (1 << 2)
+ *
+ *     mnt_optmap myoptions[] = {
+ *       { "foo",   MY_MS_FOO, MNT_MFLAG },
+ *       { "nofoo", MY_MS_FOO, MNT_MFLAG | MNT_INVERT },
+ *       { "bar=%s",MY_MS_BAR, MNT_MDATA },
+ *       { NULL }
+ *     };
+ *   </programlisting>
+ * </informalexample>
+ *
  * The libmount defines two basic built-in options maps:
  *
- *    - MNT_LINUX_MAP     -- fs-independent kernel mount options (usually MS_* flags)
- *    - MNT_USERSPACE_MAP -- userspace specific mount options (e.g. "user", "loop")
+ *	@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.
diff --git a/shlibs/mount/src/optstr.c b/shlibs/mount/src/optstr.c
index ed40cacec..19efbf3fb 100644
--- a/shlibs/mount/src/optstr.c
+++ b/shlibs/mount/src/optstr.c
@@ -7,7 +7,7 @@
 
 /**
  * SECTION: optstr
- * @title: Mount oprions string
+ * @title: Options 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
diff --git a/shlibs/mount/src/tab.c b/shlibs/mount/src/tab.c
index 71aa805b4..12de85018 100644
--- a/shlibs/mount/src/tab.c
+++ b/shlibs/mount/src/tab.c
@@ -7,7 +7,7 @@
 
 /**
  * SECTION: tab
- * @title: Filesystems container
+ * @title: FS container
  * @short_description: container for entries from fstab/mtab/mountinfo
  *
  *
@@ -15,22 +15,31 @@
  * 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:
- *
+ * <informalexample>
+ *   <programlisting>
  *	LABEL=foo	/foo	auto   rw
  *	/dev/foo	/foo	auto   rw
+ *  </programlisting>
+ * </informalexample>
  *
  * where both lines are used for the *same* device, then
- *
+ * <informalexample>
+ *  <programlisting>
  *	mnt_tab_find_source(tb, "/dev/foo", &fs);
- *
+ *  </programlisting>
+ * </informalexample>
  * will returns the second line, and
- *
+ * <informalexample>
+ *  <programlisting>
  *	mnt_tab_find_source(tb, "LABEL=foo", &fs);
- *
+ *  </programlisting>
+ * </informalexample>
  * will returns the first entry, and
- *
- *		mnt_tab_find_source(tb, "UUID=<anyuuid>", &fs);
- *
+ * <informalexample>
+ *  <programlisting>
+ *	mnt_tab_find_source(tb, "UUID=anyuuid", &fs);
+ *  </programlisting>
+ * </informalexample>
  * will returns the first entry (if UUID matches with the device).
  */
 
@@ -81,7 +90,7 @@ err:
 
 /**
  * mnt_free_tab:
- * @tab: tab pointer
+ * @tb: tab pointer
  *
  * Deallocates tab struct and all entries.
  */
@@ -255,6 +264,7 @@ int mnt_tab_get_root_fs(mnt_tab *tb, mnt_fs **root)
 /**
  * mnt_tab_next_child_fs:
  * @tb: mountinfo file (/proc/self/mountinfo)
+ * @itr: iterator
  * @parent: parental FS
  * @chld: returns the next child filesystem
  *
@@ -322,7 +332,8 @@ int mnt_tab_next_child_fs(mnt_tab *tb, mnt_iter *itr,
  * Returns: 0 on success, -1 in case of error or 1 at end of list.
  *
  * Example (list all mountpoints from fstab in backward order):
- *
+ * <informalexample>
+ *   <programlisting>
  *	mnt_fs *fs;
  *	mnt_tab *tb = mnt_new_tab("/etc/fstab");
  *	mnt_iter *itr = mnt_new_iter(MNT_ITER_BACKWARD);
@@ -334,6 +345,8 @@ int mnt_tab_next_child_fs(mnt_tab *tb, mnt_iter *itr,
  *		printf("mount point: %s\n", dir);
  *	}
  *	mnt_free_tab(fi);
+ *   </programlisting>
+ * </informalexample>
  */
 int mnt_tab_next_fs(mnt_tab *tb, mnt_iter *itr, mnt_fs **fs)
 {
@@ -366,6 +379,7 @@ again:
  * @tb: table
  * @itr: iterator
  * @match_func: function returns 1 or 0
+ * @userdata: extra data for match_func
  * @fs: returns pointer to the next matching table entry
  *
  * This function allows search in @tb.
@@ -633,6 +647,7 @@ mnt_fs *mnt_tab_find_tag(mnt_tab *tb, const char *tag,
  * mnt_tab_find_source:
  * @tb: tab pointer
  * @source: TAG or path
+ * @direction: MNT_ITER_{FORWARD,BACKWARD}
  *
  * This is high-level API for mnt_tab_find_{srcpath,tag}. You needn't to care
  * about @source format (device, LABEL, UUID, ...). This function parses @source
@@ -672,9 +687,9 @@ mnt_fs *mnt_tab_find_source(mnt_tab *tb, const char *source, int direction)
 
 /**
  * mnt_tab_fprintf:
- * @f: FILE
- * @fmt: per line printf-like format string (see MNT_MFILE_PRINTFMT)
  * @tb: tab pointer
+ * @f: FILE
+ * @fmt: per line printf-like format string (see MNT_TAB_PRINTFMT)
  *
  * Returns: 0 on success, -1 in case of error.
  */
@@ -731,7 +746,7 @@ int mnt_tab_update_file(mnt_tab *tb)
 	if (!f)
 		goto error;
 
-	if (mnt_tab_fprintf(tb, f, MNT_MFILE_PRINTFMT) != 0)
+	if (mnt_tab_fprintf(tb, f, MNT_TAB_PRINTFMT) != 0)
 		goto error;
 
 	fd = fileno(f);
diff --git a/shlibs/mount/src/utils.c b/shlibs/mount/src/utils.c
index 1f3337f24..ae2945c04 100644
--- a/shlibs/mount/src/utils.c
+++ b/shlibs/mount/src/utils.c
@@ -140,12 +140,13 @@ int mnt_fstype_is_netfs(const char *type)
  *
  * The @pattern list of filesystem can be prefixed with a global
  * "no" prefix to invert matching of the whole list. The "no" could
- * also used for individual items in the @pattern list.
+ * also used for individual items in the @pattern list. So,
+ * "nofoo,bar" has the same meaning as "nofoo,nobar".
  *
- * "nofoo,bar" has the same meaning as "nofoo,nobar"
+ * "bar"  : "nofoo,bar"		-> False   (global "no" prefix)
+ *
+ * "bar"  : "foo,bar"		-> True
  *
- * "bar" : "nofoo,bar"		-> False   (global "no" prefix)
- * "bar" : "foo,bar"		-> True
  * "bar" : "foo,nobar"		-> False
  *
  * Returns: 1 if type is matching, else 0. This function also returns
@@ -225,8 +226,9 @@ static int check_option(const char *haystack, size_t len,
  * Unlike fs type matching, nonetdev,user and nonetdev,nouser have
  * DIFFERENT meanings; each option is matched explicitly as specified.
  *
- * xxx,yyy,zzz : nozzz		-> False
- * xxx,yyy,zzz : xxx,noeee	-> True
+ * "xxx,yyy,zzz" : "nozzz"	-> False
+ *
+ * "xxx,yyy,zzz" : "xxx,noeee"	-> True
  *
  * Returns: 1 if pattern is matching, else 0. This function also returns 0
  *          if @pattern is NULL and @optstr is non-NULL.