libmount: cleanup docs

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

7 files changed, 36 insertions, 30 deletions

diff --git a/libmount/src/context.c b/libmount/src/context.c
index 2d88dc38e..f526d29bf 100644
--- a/libmount/src/context.c
+++ b/libmount/src/context.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2010 Karel Zak <kzak@redhat.com>
+ * Copyright (C) 2010,2011,2012 Karel Zak <kzak@redhat.com>
  *
  * This file may be redistributed under the terms of the
  * GNU Lesser General Public License.
@@ -175,7 +175,7 @@ int mnt_reset_context(struct libmnt_context *cxt)
  * mnt_context_reset_status:
  * @cxt: context
  *
- * Resets mount(2) and mount.<type> statuses, so mnt_context_do_mount() or
+ * Resets mount(2) and mount.type statuses, so mnt_context_do_mount() or
  * mnt_context_do_umount() could be again called with the same settings.
  *
  * BE CAREFUL -- after this soft reset the libmount will NOT parse mount
@@ -943,8 +943,10 @@ struct libmnt_cache *mnt_context_get_cache(struct libmnt_context *cxt)
 /**
  * mnt_context_set_passwd_cb:
  * @cxt: mount context
+ * @get: callback to get password
+ * @release: callback to release (delallocate) password
  *
- * Sets callbacks for encryption password.
+ * Sets callbacks for encryption password (e.g encrypted loopdev)
  *
  * Returns: 0 on success, negative number in case of error.
  */
@@ -1690,7 +1692,7 @@ int mnt_context_helper_executed(struct libmnt_context *cxt)
  * mnt_context_get_helper_status:
  * @cxt: mount context
  *
- * Return: mount.<type> exit status, result is reliable only if
+ * Return: mount.type helper exit status, result is reliable only if
  *         mnt_context_helper_executed() returns 1.
  */
 int mnt_context_get_helper_status(struct libmnt_context *cxt)
diff --git a/libmount/src/context_mount.c b/libmount/src/context_mount.c
index d38aa16be..8cbc25b27 100644
--- a/libmount/src/context_mount.c
+++ b/libmount/src/context_mount.c
@@ -597,7 +597,7 @@ int mnt_context_prepare_mount(struct libmnt_context *cxt)
  * another source or target than you have to call mnt_reset_context().
  *
  * If you want to call mount(2) for the same source and target with a diffrent
- * mount flags or fstype then you call mnt_context_reset_state() and then try
+ * mount flags or fstype then you call mnt_context_reset_status() and then try
  * again mnt_context_do_mount().
  *
  * WARNING: non-zero return code does not mean that mount(2) syscall or
@@ -705,7 +705,7 @@ int mnt_context_finalize_mount(struct libmnt_context *cxt)
  *
  * Note that this function could be called only once. If you want to mount with
  * different setting than you have to call mnt_reset_context(). It's NOT enough
- * to call mnt_context_reset_state() if you want call this function more than
+ * to call mnt_context_reset_status() if you want call this function more than
  * once, whole context has to be reseted.
  *
  * WARNING: non-zero return code does not mean that mount(2) syscall or
diff --git a/libmount/src/context_umount.c b/libmount/src/context_umount.c
index 45c7128e6..5a2ad9ec7 100644
--- a/libmount/src/context_umount.c
+++ b/libmount/src/context_umount.c
@@ -418,7 +418,7 @@ static int exec_helper(struct libmnt_context *cxt)
 /*
  * mnt_context_helper_setopt() backend.
  *
- * This function applies umount.<type> command line option (for example parsed
+ * This function applies umount.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/lock.c b/libmount/src/lock.c
index 682c74acb..73dc6c8f7 100644
--- a/libmount/src/lock.c
+++ b/libmount/src/lock.c
@@ -298,7 +298,7 @@ static int mnt_wait_mtab_lock(struct libmnt_lock *ml, struct flock *fl, time_t m
  *
  * Where does the link point to? Obvious choices are mtab and mtab~~.
  * HJLu points out that the latter leads to races. Right now we use
- * mtab~.<pid> instead.
+ * mtab~.pid instead.
  *
  *
  * The original mount locking code has used sleep(1) between attempts and
@@ -319,7 +319,7 @@ static int mnt_wait_mtab_lock(struct libmnt_lock *ml, struct flock *fl, time_t m
  * backwardly compatible code.
  *
  * Don't forget that this code has to be compatible with 3rd party mounts
- * (/sbin/mount.<foo>) and has to work with NFS.
+ * (/sbin/mount.foo) and has to work with NFS.
  * -- kzak@redhat.com [May-2009]
  */
 
diff --git a/libmount/src/optstr.c b/libmount/src/optstr.c
index 159ae62be..af5953bc6 100644
--- a/libmount/src/optstr.c
+++ b/libmount/src/optstr.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2008-2009 Karel Zak <kzak@redhat.com>
+ * Copyright (C) 2008,2009,2012 Karel Zak <kzak@redhat.com>
  *
  * This file may be redistributed under the terms of the
  * GNU Lesser General Public License.
@@ -848,7 +848,7 @@ static int set_uint_value(char **optstr, unsigned int num,
  * @valsz: size of the value
  * @next: returns pointer to the next option (optional argument)
 
- * Translates "<username>" or "useruid" to the real UID.
+ * Translates "username" or "useruid" to the real UID.
  *
  * For example:
  *	if (!mnt_optstr_get_option(optstr, "uid", &val, &valsz))
@@ -899,7 +899,7 @@ int mnt_optstr_fix_uid(char **optstr, char *value, size_t valsz, char **next)
  * @valsz: size of the value
  * @next: returns pointer to the next option (optional argument)
 
- * Translates "<groupname>" or "usergid" to the real GID.
+ * Translates "groupname" or "usergid" to the real GID.
  *
  * Returns: 0 on success, negative number in case of error.
  */
diff --git a/libmount/src/tab_diff.c b/libmount/src/tab_diff.c
index 45434fc71..c94bcfaa0 100644
--- a/libmount/src/tab_diff.c
+++ b/libmount/src/tab_diff.c
@@ -203,57 +203,57 @@ static struct tabdiff_entry *tabdiff_get_mount(struct libmnt_tabdiff *df,
 /**
  * mnt_diff_tables:
  * @df: diff handler
- * @old: old table
- * @new: new table
+ * @old_tab: old table
+ * @new_tab: new table
  *
- * Compares @old and @new, the result is stored in @df and accessible by
+ * Compares @old_tab and @new_tab, the result is stored in @df and accessible by
  * mnt_tabdiff_next_change().
  *
  * Returns: number of changes, negative number in case of error.
  */
-int mnt_diff_tables(struct libmnt_tabdiff *df, struct libmnt_table *old,
-		    struct libmnt_table *new)
+int mnt_diff_tables(struct libmnt_tabdiff *df, struct libmnt_table *old_tab,
+		    struct libmnt_table *new_tab)
 {
 	struct libmnt_fs *fs;
 	struct libmnt_iter itr;
 	int no, nn;
 
-	if (!df || !old || !new)
+	if (!df || !old_tab || !new_tab)
 		return -EINVAL;
 
 	tabdiff_reset(df);
 
-	no = mnt_table_get_nents(old);
-	nn = mnt_table_get_nents(new);
+	no = mnt_table_get_nents(old_tab);
+	nn = mnt_table_get_nents(new_tab);
 
 	if (!no && !nn)			/* both tables are empty */
 		return 0;
 
 	DBG(DIFF, mnt_debug_h(df, "analyze new=%p (%d entries), "
 				          "old=%p (%d entries)",
-				new, nn, old, no));
+				new_tab, nn, old_tab, no));
 
 	mnt_reset_iter(&itr, MNT_ITER_FORWARD);
 
 	/* all mounted or umounted */
 	if (!no && nn) {
-		while(mnt_table_next_fs(new, &itr, &fs) == 0)
+		while(mnt_table_next_fs(new_tab, &itr, &fs) == 0)
 			tabdiff_add_entry(df, NULL, fs, MNT_TABDIFF_MOUNT);
 		goto done;
 
 	} else if (no && !nn) {
-		while(mnt_table_next_fs(old, &itr, &fs) == 0)
+		while(mnt_table_next_fs(old_tab, &itr, &fs) == 0)
 			tabdiff_add_entry(df, fs, NULL, MNT_TABDIFF_UMOUNT);
 		goto done;
 	}
 
 	/* search newly mounted or modified */
-	while(mnt_table_next_fs(new, &itr, &fs) == 0) {
+	while(mnt_table_next_fs(new_tab, &itr, &fs) == 0) {
 		struct libmnt_fs *o_fs;
 		const char *src = mnt_fs_get_source(fs),
 			   *tgt = mnt_fs_get_target(fs);
 
-		o_fs = mnt_table_find_pair(old, src, tgt, MNT_ITER_FORWARD);
+		o_fs = mnt_table_find_pair(old_tab, src, tgt, MNT_ITER_FORWARD);
 		if (!o_fs)
 			/* 'fs' is not in the old table -- so newly mounted */
 			tabdiff_add_entry(df, NULL, fs, MNT_TABDIFF_MOUNT);
@@ -269,11 +269,11 @@ int mnt_diff_tables(struct libmnt_tabdiff *df, struct libmnt_table *old,
 
 	/* search umounted or moved */
 	mnt_reset_iter(&itr, MNT_ITER_FORWARD);
-	while(mnt_table_next_fs(old, &itr, &fs) == 0) {
+	while(mnt_table_next_fs(old_tab, &itr, &fs) == 0) {
 		const char *src = mnt_fs_get_source(fs),
 			   *tgt = mnt_fs_get_target(fs);
 
-		if (!mnt_table_find_pair(new, src, tgt, MNT_ITER_FORWARD)) {
+		if (!mnt_table_find_pair(new_tab, src, tgt, MNT_ITER_FORWARD)) {
 			struct tabdiff_entry *de;
 
 			de = tabdiff_get_mount(df, src,	mnt_fs_get_id(fs));
diff --git a/libmount/src/version.c b/libmount/src/version.c
index e3bc5ca8a..00e4f9961 100644
--- a/libmount/src/version.c
+++ b/libmount/src/version.c
@@ -68,16 +68,20 @@ int mnt_get_library_version(const char **ver_string)
  * @features: returns pointer to the static array of strings, the array is
  *            terminated by NULL.
  *
- * Example:
+ * Returns: number of items in the features array not including the last NULL,
+ *          or less then zero in case of error
  *
+ * Example:
+ * <informalexample>
+ *   <programlisting>
  *	const char *features;
  *
  *	mnt_get_library_features(&features);
  *	while (features && *features)
  *		printf("%s\n", *features++);
+ *   </programlisting>
+ * </informalexample>
  *
- * Returns: number of items in the features array not including the last NULL,
- *          or less then zero in case of error
  */
 int mnt_get_library_features(const char ***features)
 {