libmount: cleanup docs

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

13 files changed, 206 insertions, 153 deletions

diff --git a/libmount/docs/Makefile.am b/libmount/docs/Makefile.am
index 3e087d294..fe0545a96 100644
--- a/libmount/docs/Makefile.am
+++ b/libmount/docs/Makefile.am
@@ -34,7 +34,7 @@ SCAN_OPTIONS=
 
 # Extra options to supply to gtkdoc-mkdb.
 # e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
-MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space mount
+MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space mnt
 
 # Extra options to supply to gtkdoc-mktmpl
 # e.g. MKTMPL_OPTIONS=--only-section-tmpl
diff --git a/libmount/docs/libmount-docs.xml b/libmount/docs/libmount-docs.xml
index 75802a282..b948e7408 100644
--- a/libmount/docs/libmount-docs.xml
+++ b/libmount/docs/libmount-docs.xml
@@ -9,7 +9,7 @@
     <title>libmount Reference Manual</title>
     <releaseinfo>for libmount version &version;</releaseinfo>
     <copyright>
-      <year>2010</year>
+      <year>2010-2011</year>
       <holder>Karel Zak &lt;kzak@redhat.com&gt;</holder>
     </copyright>
   </bookinfo>
@@ -31,23 +31,26 @@ available from ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
   <part>
     <title>High-level API</title>
     <xi:include href="xml/context.xml"/>
+    <xi:include href="xml/context-mount.xml"/>
+    <xi:include href="xml/context-umount.xml"/>
   </part>
   <part>
     <title>Files parsing</title>
-    <xi:include href="xml/tab.xml"/>
+    <xi:include href="xml/table.xml"/>
     <xi:include href="xml/fs.xml"/>
   </part>
   <part>
+    <title>Tables management</title>
+    <xi:include href="xml/lock.xml"/>
+    <xi:include href="xml/update.xml"/>
+    <xi:include href="xml/tabdiff.xml"/>
+  </part>
+  <part>
     <title>Mount options</title>
     <xi:include href="xml/optstr.xml"/>
     <xi:include href="xml/optmap.xml"/>
   </part>
   <part>
-    <title>Mtab management</title>
-    <xi:include href="xml/lock.xml"/>
-    <xi:include href="xml/update.xml"/>
-  </part>
-  <part>
     <title>Misc</title>
     <xi:include href="xml/init.xml"/>
     <xi:include href="xml/cache.xml"/>
@@ -55,7 +58,6 @@ available from ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
     <xi:include href="xml/utils.xml"/>
     <xi:include href="xml/version.xml"/>
   </part>
-
   <index id="api-index-full">
     <title>API Index</title>
     <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
diff --git a/libmount/docs/libmount-sections.txt b/libmount/docs/libmount-sections.txt
index f79374d90..e58dbcdfc 100644
--- a/libmount/docs/libmount-sections.txt
+++ b/libmount/docs/libmount-sections.txt
@@ -1,73 +1,91 @@
 <SECTION>
-<FILE>init</FILE>
-mnt_init_debug
-</SECTION>
-
-<SECTION>
-<FILE>version</FILE>
-mnt_parse_version_string
-mnt_get_library_version
-</SECTION>
-
-<SECTION>
-<FILE>utils</FILE>
-mnt_fstype_is_netfs
-mnt_fstype_is_pseudofs
-mnt_get_fstab_path
-mnt_get_mtab_path
-mnt_has_regular_mtab
-mnt_mangle
-mnt_match_fstype
-mnt_match_options
-mnt_unmangle
-</SECTION>
-
-<SECTION>
 <FILE>cache</FILE>
+mnt_new_cache
+mnt_free_cache
 mnt_cache_device_has_tag
 mnt_cache_find_tag_value
 mnt_cache_read_tags
-mnt_free_cache
 mnt_get_fstype
-mnt_new_cache
+mnt_pretty_path
 mnt_resolve_path
 mnt_resolve_spec
 mnt_resolve_tag
 </SECTION>
 
 <SECTION>
-<FILE>optstr</FILE>
-mnt_optstr_append_option
-mnt_optstr_apply_flags
-mnt_optstr_get_flags
-mnt_optstr_get_option
-mnt_optstr_get_options
-mnt_optstr_next_option
-mnt_optstr_prepend_option
-mnt_optstr_remove_option
-mnt_optstr_set_option
-mnt_split_optstr
-</SECTION>
-
-<SECTION>
-<FILE>iter</FILE>
-mnt_free_iter
-mnt_iter_get_direction
-mnt_new_iter
-mnt_reset_iter
+<FILE>context</FILE>
+mnt_free_context
+mnt_new_context
+mnt_reset_context
+mnt_context_append_options
+mnt_context_apply_fstab
+mnt_context_disable_canonicalize
+mnt_context_disable_helpers
+mnt_context_disable_mtab
+mnt_context_enable_fake
+mnt_context_enable_force
+mnt_context_enable_lazy
+mnt_context_enable_loopdel
+mnt_context_enable_rdonly_umount
+mnt_context_enable_sloppy
+mnt_context_enable_verbose
+mnt_context_get_cache
+mnt_context_get_fs
+mnt_context_get_fstab
+mnt_context_get_fstype
+mnt_context_get_lock
+mnt_context_get_mflags
+mnt_context_get_mtab
+mnt_context_get_optsmode
+mnt_context_get_source
+mnt_context_get_status
+mnt_context_get_table
+mnt_context_get_target
+mnt_context_get_user_mflags
+mnt_context_helper_setopt
+mnt_context_init_helper
+mnt_context_is_fake
+mnt_context_is_force
+mnt_context_is_fs_mounted
+mnt_context_is_lazy
+mnt_context_is_nomtab
+mnt_context_is_rdonly_umount
+mnt_context_is_restricted
+mnt_context_is_sloppy
+mnt_context_is_verbose
+mnt_context_set_cache
+mnt_context_set_fs
+mnt_context_set_fstab
+mnt_context_set_fstype
+mnt_context_set_fstype_pattern
+mnt_context_set_mflags
+mnt_context_set_mountdata
+mnt_context_set_options
+mnt_context_set_options_pattern
+mnt_context_set_optsmode
+mnt_context_set_source
+mnt_context_set_syscall_status
+mnt_context_set_tables_errcb
+mnt_context_set_target
+mnt_context_set_user_mflags
+mnt_context_strerror
 </SECTION>
 
 <SECTION>
-<FILE>optmap</FILE>
-mnt_get_builtin_optmap
+<FILE>context-mount</FILE>
+mnt_context_do_mount
+mnt_context_finalize_mount
+mnt_context_mount
+mnt_context_next_mount
+mnt_context_prepare_mount
 </SECTION>
 
 <SECTION>
-<FILE>lock</FILE>
-mnt_free_lock
-mnt_lock_file
-mnt_new_lock
-mnt_unlock_file
+<FILE>context-umount</FILE>
+mnt_context_do_umount
+mnt_context_finalize_umount
+mnt_context_prepare_umount
+mnt_context_umount
 </SECTION>
 
 <SECTION>
@@ -76,10 +94,7 @@ mnt_copy_fs
 mnt_free_fs
 mnt_free_mntent
 mnt_fs_append_attributes
-mnt_fs_append_fs_options
 mnt_fs_append_options
-mnt_fs_append_user_options
-mnt_fs_append_vfs_options
 mnt_fs_get_attribute
 mnt_fs_get_attributes
 mnt_fs_get_bindsrc
@@ -89,6 +104,7 @@ mnt_fs_get_fs_options
 mnt_fs_get_fstype
 mnt_fs_get_id
 mnt_fs_get_option
+mnt_fs_get_options
 mnt_fs_get_parent_id
 mnt_fs_get_passno
 mnt_fs_get_root
@@ -99,20 +115,17 @@ mnt_fs_get_target
 mnt_fs_get_userdata
 mnt_fs_get_user_options
 mnt_fs_get_vfs_options
+mnt_fs_is_kernel
 mnt_fs_match_fstype
 mnt_fs_match_options
 mnt_fs_match_source
 mnt_fs_match_target
 mnt_fs_prepend_attributes
-mnt_fs_prepend_fs_options
 mnt_fs_prepend_options
-mnt_fs_prepend_user_options
-mnt_fs_prepend_vfs_options
 mnt_fs_print_debug
 mnt_fs_set_attributes
 mnt_fs_set_bindsrc
 mnt_fs_set_freq
-mnt_fs_set_fs_options
 mnt_fs_set_fstype
 mnt_fs_set_options
 mnt_fs_set_passno
@@ -120,17 +133,58 @@ mnt_fs_set_root
 mnt_fs_set_source
 mnt_fs_set_target
 mnt_fs_set_userdata
-mnt_fs_set_user_options
-mnt_fs_set_vfs_options
 mnt_fs_strdup_options
-mnt_new_fs
 mnt_fs_to_mntent
+mnt_new_fs
+mnt_reset_fs
+</SECTION>
+
+<SECTION>
+<FILE>init</FILE>
+mnt_init_debug
+</SECTION>
+
+<SECTION>
+<FILE>iter</FILE>
+mnt_free_iter
+mnt_iter_get_direction
+mnt_new_iter
+mnt_reset_iter
+</SECTION>
+
+<SECTION>
+<FILE>lock</FILE>
+mnt_free_lock
+mnt_lock_file
+mnt_new_lock
+mnt_unlock_file
+mnt_lock_block_signals
+</SECTION>
+
+<SECTION>
+<FILE>optmap</FILE>
+mnt_get_builtin_optmap
+</SECTION>
+
+<SECTION>
+<FILE>optstr</FILE>
+mnt_optstr_append_option
+mnt_optstr_apply_flags
+mnt_optstr_get_flags
+mnt_optstr_get_option
+mnt_optstr_get_options
+mnt_optstr_next_option
+mnt_optstr_prepend_option
+mnt_optstr_remove_option
+mnt_optstr_set_option
+mnt_split_optstr
 </SECTION>
 
 <SECTION>
-<FILE>tab</FILE>
+<FILE>table</FILE>
 mnt_free_table
 mnt_new_table
+mnt_reset_table
 mnt_new_table_from_dir
 mnt_new_table_from_file
 mnt_table_add_fs
@@ -144,6 +198,7 @@ mnt_table_get_cache
 mnt_table_get_name
 mnt_table_get_nents
 mnt_table_get_root_fs
+mnt_table_is_fs_mounted
 mnt_table_next_child_fs
 mnt_table_next_fs
 mnt_table_parse_file
@@ -157,6 +212,14 @@ mnt_table_set_parser_errcb
 </SECTION>
 
 <SECTION>
+<FILE>tabdiff</FILE>
+mnt_new_tabdiff
+mnt_free_tabdiff
+mnt_tabdiff_next_change
+mnt_diff_tables
+</SECTION>
+
+<SECTION>
 <FILE>update</FILE>
 mnt_free_update
 mnt_new_update
@@ -170,57 +233,34 @@ mnt_update_table
 </SECTION>
 
 <SECTION>
-<FILE>context</FILE>
-mnt_context_init_helper
-mnt_context_helper_setopt
-mnt_context_append_options
-mnt_context_apply_fstab
-mnt_context_disable_canonicalize
-mnt_context_disable_helpers
-mnt_context_disable_mtab
-mnt_context_do_mount
-mnt_context_do_umount
-mnt_context_enable_fake
-mnt_context_enable_force
-mnt_context_enable_lazy
-mnt_context_enable_loopdel
-mnt_context_enable_rdonly_umount
-mnt_context_enable_sloppy
-mnt_context_enable_verbose
-mnt_context_finalize_mount
-mnt_context_finalize_umount
-mnt_context_get_cache
-mnt_context_get_fs
-mnt_context_get_fstab
-mnt_context_get_fstype
-mnt_context_get_lock
-mnt_context_get_mflags
-mnt_context_get_mtab
-mnt_context_get_source
-mnt_context_get_status
-mnt_context_get_target
-mnt_context_get_user_mflags
-mnt_context_is_restricted
-mnt_context_mount
-mnt_context_prepare_mount
-mnt_context_prepare_umount
-mnt_context_set_cache
-mnt_context_set_fs
-mnt_context_set_fstab
-mnt_context_set_fstype
-mnt_context_set_fstype_pattern
-mnt_context_set_mflags
-mnt_context_set_mountdata
-mnt_context_set_options
-mnt_context_set_options_pattern
-mnt_context_set_optsmode
-mnt_context_set_source
-mnt_context_set_target
-mnt_context_set_user_mflags
-mnt_context_strerror
-mnt_context_umount
-mnt_free_context
-mnt_new_context
-mnt_reset_context
+<FILE>utils</FILE>
+mnt_fstype_is_netfs
+mnt_fstype_is_pseudofs
+mnt_get_fstab_path
+mnt_get_fstype
+mnt_get_library_version
+mnt_get_mtab_path
+mnt_has_regular_mtab
+mnt_mangle
+mnt_match_fstype
+mnt_match_options
+mnt_unmangle
 </SECTION>
 
+<SECTION>
+<FILE>version</FILE>
+mnt_parse_version_string
+mnt_get_library_version
+</SECTION>
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/libmount/src/cache.c b/libmount/src/cache.c
index e3bdcd089..7298b2820 100644
--- a/libmount/src/cache.c
+++ b/libmount/src/cache.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2009 Karel Zak <kzak@redhat.com>
+ * Copyright (C) 2009-2011 Karel Zak <kzak@redhat.com>
  *
  * This file may be redistributed under the terms of the
  * GNU Lesser General Public License.
@@ -11,7 +11,7 @@
  * @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.
+ * paths. The cache uses libblkid as a backend for TAGs resolution.
  *
  * All returned paths are always canonicalized.
  */
@@ -450,7 +450,7 @@ char *mnt_get_fstype(const char *devname, int *ambi, struct libmnt_cache *cache)
  *
  * Converts path:
  *	- to the absolute path
- *	- /dev/dm-N to /dev/mapper/<name>
+ *	- /dev/dm-N to /dev/mapper/name
  *
  * Returns: absolute path or NULL in case of error. The result has to be
  * deallocated by free() if @cache is NULL.
@@ -501,7 +501,7 @@ error:
  *
  * Converts path:
  *	- to the absolute path
- *	- /dev/dm-N to /dev/mapper/<name>
+ *	- /dev/dm-N to /dev/mapper/name
  *	- /dev/loopN to the loop backing filename
  *	- empty path (NULL) to 'none'
  *
diff --git a/libmount/src/context.c b/libmount/src/context.c
index ff199ea2e..422469bf8 100644
--- a/libmount/src/context.c
+++ b/libmount/src/context.c
@@ -7,7 +7,7 @@
 
 /**
  * SECTION: context
- * @title: Mount/umount context
+ * @title: Library high-level context
  * @short_description: high-level API to mount/umount devices.
  *
  * <informalexample>
@@ -1603,11 +1603,11 @@ int mnt_context_strerror(struct libmnt_context *cxt, char *buf, size_t bufsiz)
  * @action: MNT_ACT_{UMOUNT,MOUNT}
  * @flags: not used
  *
- * This function infors libmount that used from [u]mount.<type> helper.
+ * This function infors libmount that used from [u]mount.type helper.
  *
  * The function also calls mnt_context_disable_helpers() to avoid recursive
- * mount.<type> helpers calling. It you really want to call another
- * mount.<type> helper from your helper than you have to explicitly enable this
+ * mount.type helpers calling. It you really want to call another
+ * mount.type helper from your helper than you have to explicitly enable this
  * feature by:
  *
  *	 mnt_context_disable_helpers(cxt, FALSE);
@@ -1633,7 +1633,7 @@ int mnt_context_init_helper(struct libmnt_context *cxt, int action, int flags)
  * @c: getopt() result
  * @arg: getopt() optarg
  *
- * This function applies [u]mount.<type> command line option (for example parsed
+ * This function applies [u]mount.type command line option (for example parsed
  * by getopt() or getopt_long()) to @cxt. All unknown options are ignored and
  * then 1 is returned.
  *
diff --git a/libmount/src/context_mount.c b/libmount/src/context_mount.c
index 53bb3a735..f9642e5a7 100644
--- a/libmount/src/context_mount.c
+++ b/libmount/src/context_mount.c
@@ -5,6 +5,12 @@
  * GNU Lesser General Public License.
  */
 
+/**
+ * SECTION: context-mount
+ * @title: Mount context
+ * @short_description: high-level API to mount operation.
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <sys/types.h>
@@ -122,7 +128,7 @@ done:
 
 /*
  * Converts already evalulated and fixed options to the form that is compatible
- * with /sbin/mount.<type> helpers.
+ * with /sbin/mount.type helpers.
  */
 static int generate_helper_optstr(struct libmnt_context *cxt, char **optstr)
 {
@@ -224,7 +230,7 @@ static int evaluate_permissions(struct libmnt_context *cxt)
 /*
  * mnt_context_helper_setopt() backend
  *
- * This function applies mount.<type> command line option (for example parsed
+ * This function applies mount.type command line option (for example parsed
  * by getopt() or getopt_long()) to @cxt. All unknown options are ignored and
  * then 1 is returned.
  *
@@ -535,7 +541,7 @@ int mnt_context_prepare_mount(struct libmnt_context *cxt)
  * mnt_context_do_mount
  * @cxt: context
  *
- * Call mount(2) or mount.<type> helper. Unnecessary for mnt_context_mount().
+ * Call mount(2) or mount.type helper. Unnecessary for mnt_context_mount().
  *
  * WARNING: non-zero return code does not mean that mount(2) syscall or
  *          umount.type helper wasn't sucessfully called.
@@ -653,15 +659,15 @@ int mnt_context_mount(struct libmnt_context *cxt)
  * mnt_context_get_fstab()). See also mnt_context_set_fstab().
  *
  * You can filter out filesystems by:
- *	mnt_context_set_options_pattern() to simulate mount -a -O <pattern>
- *	mnt_context_set_fstype_pattern()  to simulate mount -a -t <pattern>
+ *	mnt_context_set_options_pattern() to simulate mount -a -O pattern
+ *	mnt_context_set_fstype_pattern()  to simulate mount -a -t pattern
  *
  * If the filesystem is already mounted or does not match defined criteria,
  * then the mnt_context_next_mount() function returns zero, but the @ignored is
  * non-zero. Note that the root filesystem and filesystems with "noauto" option
  * are always ignored.
  *
- * If mount(2) syscall or mount.<type> helper failed, then the
+ * If mount(2) syscall or mount.type helper failed, then the
  * mnt_context_next_mount() function returns zero, but the @mntrc is non-zero.
  * Use also mnt_context_get_status() to check if the filesystem was
  * successfully mounted.
diff --git a/libmount/src/context_umount.c b/libmount/src/context_umount.c
index 184a51efe..5c52be1cf 100644
--- a/libmount/src/context_umount.c
+++ b/libmount/src/context_umount.c
@@ -5,6 +5,12 @@
  * GNU Lesser General Public License.
  */
 
+/**
+ * SECTION: context-umount
+ * @title: Umount context
+ * @short_description: high-level API to umount operation.
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <sys/types.h>
diff --git a/libmount/src/fs.c b/libmount/src/fs.c
index b00b0ede8..303a5d6f1 100644
--- a/libmount/src/fs.c
+++ b/libmount/src/fs.c
@@ -8,7 +8,7 @@
 /**
  * SECTION: fs
  * @title: Filesystem
- * @short_description: struct libmnt_fs represents one entry in fstab/mtab/mountinfo
+ * @short_description: represents one entry from fstab, mtab, or mountinfo file
  *
  */
 #include <stdio.h>
diff --git a/libmount/src/lock.c b/libmount/src/lock.c
index 53c1115ec..2e3ca533e 100644
--- a/libmount/src/lock.c
+++ b/libmount/src/lock.c
@@ -7,7 +7,7 @@
 
 /**
  * SECTION: lock
- * @title: locking
+ * @title: Locking
  * @short_description: locking methods for /etc/mtab or another libmount files
  *
  * The mtab lock is backwardly compatible with the standard linux /etc/mtab
diff --git a/libmount/src/optstr.c b/libmount/src/optstr.c
index 78b7571d2..216d9ac1e 100644
--- a/libmount/src/optstr.c
+++ b/libmount/src/optstr.c
@@ -11,8 +11,7 @@
  * @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.
+ * in string.
  */
 
 #include <string.h>
diff --git a/libmount/src/tab.c b/libmount/src/tab.c
index 227c5aa43..e52878be1 100644
--- a/libmount/src/tab.c
+++ b/libmount/src/tab.c
@@ -6,10 +6,9 @@
  */
 
 /**
- * SECTION: tab
+ * SECTION: table
  * @title: Table of filesystems
- * @short_description: container for entries from fstab/mtab/mountinfo
- *
+ * @short_description: container for entries from fstab, mtab or mountinfo
  *
  * Note that mnt_table_find_* functions are mount(8) compatible. These functions
  * try to found an entry in more iterations where the first attempt is always
diff --git a/libmount/src/tab_diff.c b/libmount/src/tab_diff.c
index d1a17bcb9..5a9c9bb44 100644
--- a/libmount/src/tab_diff.c
+++ b/libmount/src/tab_diff.c
@@ -7,7 +7,7 @@
 
 /**
  * SECTION: tabdiff
- * @title: monitor mountinfo file
+ * @title: Monitor mountinfo changes
  * @short_description: monitor changes in the list of the mounted filesystems
  */
 
diff --git a/libmount/src/tab_update.c b/libmount/src/tab_update.c
index 39d61e66c..defdc2eea 100644
--- a/libmount/src/tab_update.c
+++ b/libmount/src/tab_update.c
@@ -7,13 +7,14 @@
 
 /**
  * SECTION: update
- * @title: mtab managment
- * @short_description: userspace mount information management.
+ * @title: Tables update
+ * @short_description: userspace mount information management
  *
- * The struct libmnt_update provides abstraction to manage mount options in userspace independently on
- * system configuration. This low-level API works on system with and without /etc/mtab. On 
- * systems without the regular /etc/mtab file are userspace mount options (e.g. user=)
- * stored to the /run/mount/utab file.
+ * The struct libmnt_update provides abstraction to manage mount options in
+ * userspace independently on system configuration. This low-level API works on
+ * system with and without /etc/mtab. On systems without the regular /etc/mtab
+ * file are userspace mount options (e.g. user=) stored to the /run/mount/utab
+ * file.
  *
  * It's recommended to use high-level struct libmnt_context API.
  */