libblkid: update docs

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

10 files changed, 88 insertions, 33 deletions

diff --git a/libblkid/docs/Makefile.am b/libblkid/docs/Makefile.am
index 8ef3b239b..eb84f7905 100644
--- a/libblkid/docs/Makefile.am
+++ b/libblkid/docs/Makefile.am
@@ -30,7 +30,7 @@ SCANGOBJ_OPTIONS=
 
 # Extra options to supply to gtkdoc-scan.
 # e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
-SCAN_OPTIONS=
+SCAN_OPTIONS=--deprecated-guards="BLKID_DISABLE_DEPRECATED"
 
 # Extra options to supply to gtkdoc-mkdb.
 # e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
diff --git a/libblkid/docs/libblkid-docs.xml b/libblkid/docs/libblkid-docs.xml
index c99192a96..003dcd518 100644
--- a/libblkid/docs/libblkid-docs.xml
+++ b/libblkid/docs/libblkid-docs.xml
@@ -9,7 +9,7 @@
     <title>libblkid Reference Manual</title>
     <releaseinfo>for libblkid version &version;</releaseinfo>
     <copyright>
-      <year>2009</year>
+      <year>2009-2011</year>
       <holder>Karel Zak &lt;kzak@redhat.com&gt;</holder>
     </copyright>
   </bookinfo>
diff --git a/libblkid/docs/libblkid-sections.txt b/libblkid/docs/libblkid-sections.txt
index 47675f4ae..cef0b1194 100644
--- a/libblkid/docs/libblkid-sections.txt
+++ b/libblkid/docs/libblkid-sections.txt
@@ -1,6 +1,7 @@
 <SECTION>
 <FILE>evaluate</FILE>
 blkid_evaluate_tag
+blkid_evaluate_spec
 </SECTION>
 
 <SECTION>
@@ -10,6 +11,7 @@ blkid_gc_cache
 blkid_get_cache
 blkid_put_cache
 blkid_probe_all
+blkid_probe_all_removable
 blkid_probe_all_new
 blkid_verify
 </SECTION>
@@ -41,10 +43,14 @@ blkid_free_probe
 blkid_new_probe
 blkid_new_probe_from_filename
 blkid_probe_get_devno
+blkid_probe_get_fd
 blkid_probe_get_sectorsize
 blkid_probe_get_sectors
 blkid_probe_get_size
+blkid_probe_get_offset
+blkid_probe_get_wholedisk_devno
 blkid_probe_set_device
+blkid_probe_is_wholedisk
 blkid_reset_probe
 </SECTION>
 
@@ -67,10 +73,14 @@ blkid_partition
 blkid_parttable
 blkid_probe_enable_partitions
 blkid_probe_set_partitions_flags
+blkid_probe_filter_partitions_type
+blkid_probe_invert_partitions_filter
+blkid_probe_reset_partitions_filter
 <SUBSECTION>
 blkid_known_pttype
 <SUBSECTION>
 blkid_partition_get_name
+blkid_partition_get_flags
 blkid_partition_get_partno
 blkid_partition_get_size
 blkid_partition_get_start
@@ -84,6 +94,8 @@ blkid_partition_is_primary
 <SUBSECTION>
 blkid_partlist_get_partition
 blkid_partlist_numof_partitions
+blkid_partlist_devno_to_partition
+blkid_partlist_get_table
 <SUBSECTION>
 blkid_parttable_get_offset
 blkid_parttable_get_parent
@@ -97,6 +109,7 @@ blkid_probe_get_partitions
 blkid_probe_enable_superblocks
 <SUBSECTION>
 blkid_known_fstype
+blkid_superblocks_get_name
 <SUBSECTION>
 blkid_probe_filter_superblocks_type
 blkid_probe_filter_superblocks_usage
@@ -140,6 +153,38 @@ blkid_get_library_version
 blkid_parse_tag_string
 blkid_parse_version_string
 blkid_send_uevent
+BLKID_VERSION
+BLKID_DATE
+BLKID_FLTR_NOTIN
+BLKID_FLTR_ONLYIN
+BLKID_DEV_CREATE
+BLKID_DEV_FIND
+BLKID_DEV_NORMAL
+BLKID_DEV_VERIFY
+BLKID_PARTS_ENTRY_DETAILS
+BLKID_PARTS_FORCE_GPT
+BLKID_PROBREQ_LABEL
+BLKID_PROBREQ_LABELRAW
+BLKID_PROBREQ_SECTYPE
+BLKID_PROBREQ_TYPE
+BLKID_PROBREQ_USAGE
+BLKID_PROBREQ_UUID
+BLKID_PROBREQ_UUIDRAW
+BLKID_PROBREQ_VERSION
+BLKID_SUBLKS_DEFAULT
+BLKID_SUBLKS_LABEL
+BLKID_SUBLKS_LABELRAW
+BLKID_SUBLKS_MAGIC
+BLKID_SUBLKS_SECTYPE
+BLKID_SUBLKS_TYPE
+BLKID_SUBLKS_USAGE
+BLKID_SUBLKS_UUID
+BLKID_SUBLKS_UUIDRAW
+BLKID_SUBLKS_VERSION
+BLKID_USAGE_CRYPTO
+BLKID_USAGE_FILESYSTEM
+BLKID_USAGE_OTHER
+BLKID_USAGE_RAID
 </SECTION>
 
 
diff --git a/libblkid/src/blkid.h.in b/libblkid/src/blkid.h.in
index c145ccfd3..a74c810e3 100644
--- a/libblkid/src/blkid.h.in
+++ b/libblkid/src/blkid.h.in
@@ -234,7 +234,13 @@ extern int blkid_probe_set_superblocks_flags(blkid_probe pr, int flags);
 extern int blkid_probe_reset_superblocks_filter(blkid_probe pr);
 extern int blkid_probe_invert_superblocks_filter(blkid_probe pr);
 
+/**
+ * BLKID_FLTR_NOTIN
+ */
 #define BLKID_FLTR_NOTIN		1
+/**
+ * BLKID_FLTR_ONLYIN
+ */
 #define BLKID_FLTR_ONLYIN		2
 extern int blkid_probe_filter_superblocks_type(blkid_probe pr, int flag, char *names[]);
 
@@ -313,9 +319,11 @@ extern int blkid_probe_lookup_value(blkid_probe pr, const char *name,
                         const char **data, size_t *len);
 extern int blkid_probe_has_value(blkid_probe pr, const char *name);
 
-/***
+/*
  * Deprecated functions/macros
  */
+#ifndef BLKID_DISABLE_DEPRECATED
+
 #define BLKID_PROBREQ_LABEL     BLKID_SUBLKS_LABEL
 #define BLKID_PROBREQ_LABELRAW  BLKID_SUBLKS_LABELRAW
 #define BLKID_PROBREQ_UUID      BLKID_SUBLKS_UUID
@@ -331,6 +339,8 @@ extern int blkid_probe_filter_types(blkid_probe pr, int flag, char *names[]);
 extern int blkid_probe_invert_filter(blkid_probe pr);
 extern int blkid_probe_reset_filter(blkid_probe pr);
 
+#endif /* BLKID_DISABLE_DEPRECATED */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/libblkid/src/evaluate.c b/libblkid/src/evaluate.c
index 88c6830e8..d20b922f6 100644
--- a/libblkid/src/evaluate.c
+++ b/libblkid/src/evaluate.c
@@ -29,16 +29,17 @@
 
 /**
  * SECTION:evaluate
- * @title: Tags evaluation
+ * @title: Tags and Spec evaluation
  * @short_description: top-level API for LABEL and UUID evaluation.
  *
  * This API provides very simple and portable way how evaluate LABEL and UUID
- * tags.  The blkid_evaluate_tag() works on 2.4 and 2.6 systems and on systems
- * with or without udev. Currently, the libblkid library supports "udev" and
- * "scan" methods. The "udev" method uses udev /dev/disk/by-* symlinks and the
- * "scan" method scans all block devices from the /proc/partitions file. The
- * evaluation could be controlled by the /etc/blkid.conf config file. The
- * default is to try "udev" and then "scan" method.
+ * tags.  The blkid_evaluate_tag() and blkid_evaluate_spec() work on 2.4 and
+ * 2.6 systems and on systems with or without udev. Currently, the libblkid
+ * library supports "udev" and "scan" methods. The "udev" method uses udev
+ * /dev/disk/by-* symlinks and the "scan" method scans all block devices from
+ * the /proc/partitions file. The evaluation could be controlled by the
+ * /etc/blkid.conf config file. The default is to try "udev" and then "scan"
+ * method.
  *
  * The blkid_evaluate_tag() also automatically informs udevd when an obsolete
  * /dev/disk/by-* symlink is detected.
@@ -91,6 +92,7 @@ done:
 /**
  * blkid_send_uevent:
  * @devname: absolute path to the device
+ * @action: event string
  *
  * Returns: -1 in case of failure, or 0 on success.
  */
@@ -265,7 +267,7 @@ out:
  * @cache: pointer to cache (or NULL when you don't want to re-use the cache)
  *
  * All returned paths are canonicalized, device-mapper paths are converted
- * to the /dev/mapper/<name> format.
+ * to the /dev/mapper/name format.
  *
  * Returns: allocated string with a device name.
  */
diff --git a/libblkid/src/partitions/partitions.c b/libblkid/src/partitions/partitions.c
index dcb479e1f..a73181234 100644
--- a/libblkid/src/partitions/partitions.c
+++ b/libblkid/src/partitions/partitions.c
@@ -24,7 +24,7 @@
 #include "sysfs.h"
 
 /**
- * SECTION:partitions
+ * SECTION: partitions
  * @title: Partitions probing
  * @short_description: partitions tables detection and parsing
  *
@@ -53,7 +53,7 @@
  *
  * @PART_ENTRY_SIZE: size of the partition
  *
- * @PART_ENTRY_DISK: whole-disk <maj:min>
+ * @PART_ENTRY_DISK: whole-disk maj:min
  *
  * Example:
  *
@@ -265,8 +265,9 @@ int blkid_probe_invert_partitions_filter(blkid_probe pr)
  * @flag: filter BLKID_FLTR_{NOTIN,ONLYIN} flag
  * @names: NULL terminated array of probing function names (e.g. "vfat").
  *
- *  BLKID_FLTR_NOTIN  - probe for all items which are NOT IN @names
- *  BLKID_FLTR_ONLYIN - probe for items which are IN @names
+ *  %BLKID_FLTR_NOTIN  - probe for all items which are NOT IN @names
+ *
+ *  %BLKID_FLTR_ONLYIN - probe for items which are IN @names
  *
  * Returns: 0 on success, or -1 in case of error.
  */
@@ -855,8 +856,9 @@ int blkid_partlist_numof_partitions(blkid_partlist ls)
 
 /**
  * blkid_partlist_get_table:
+ * @ls: partitions list
  *
- * Returns top-level partition table or NULL of there is not a partition table
+ * Returns: top-level partition table or NULL of there is not a partition table
  * on the device.
  */
 blkid_parttable blkid_partlist_get_table(blkid_partlist ls)
@@ -1022,8 +1024,6 @@ blkid_partition blkid_parttable_get_parent(blkid_parttable tab)
  * blkid_parttable_get_offset:
  * @tab: partition table
  *
- * Returns: position (in bytes) of the partition table or -1 in case of error.
- *
  * Note the position is relative to begin of the device as defined by
  * blkid_probe_set_device() for primary partition table, and relative
  * to parental partition for nested patition tables.
@@ -1040,6 +1040,9 @@ blkid_partition blkid_parttable_get_parent(blkid_parttable tab)
  *	offset += blkid_partition_get_start(parent);
  *   </programlisting>
  * </informalexample>
+
+ * Returns: position (in bytes) of the partition table or -1 in case of error.
+ *
  */
 blkid_loff_t blkid_parttable_get_offset(blkid_parttable tab)
 {
diff --git a/libblkid/src/probe.c b/libblkid/src/probe.c
index 85db814f0..3c691cf7d 100644
--- a/libblkid/src/probe.c
+++ b/libblkid/src/probe.c
@@ -978,7 +978,7 @@ done:
  * @pr: prober
  *
  * This function gathers probing results from all enabled chains. Same as
- * blkid_so_safeprobe() but does not check for collision between probing
+ * blkid_do_safeprobe() but does not check for collision between probing
  * result.
  *
  * This is string-based NAME=value interface only.
diff --git a/libblkid/src/superblocks/superblocks.c b/libblkid/src/superblocks/superblocks.c
index e177667d2..9b618b28f 100644
--- a/libblkid/src/superblocks/superblocks.c
+++ b/libblkid/src/superblocks/superblocks.c
@@ -224,8 +224,9 @@ int blkid_probe_invert_superblocks_filter(blkid_probe pr)
  * @flag: filter BLKID_FLTR_{NOTIN,ONLYIN} flag
  * @names: NULL terminated array of probing function names (e.g. "vfat").
  *
- *  BLKID_FLTR_NOTIN  - probe for all items which are NOT IN @names
- *  BLKID_FLTR_ONLYIN - probe for items which are IN @names
+ *  %BLKID_FLTR_NOTIN  - probe for all items which are NOT IN @names;
+ *
+ *  %BLKID_FLTR_ONLYIN - probe for items which are IN @names
  *
  * Returns: 0 on success, or -1 in case of error.
  */
@@ -240,8 +241,9 @@ int blkid_probe_filter_superblocks_type(blkid_probe pr, int flag, char *names[])
  * @flag: filter BLKID_FLTR_{NOTIN,ONLYIN} flag
  * @usage: BLKID_USAGE_* flags
  *
- *  BLKID_FLTR_NOTIN  - probe for all items which are NOT IN @usage
- *  BLKID_FLTR_ONLYIN - probe for items which are IN @usage
+ *  %BLKID_FLTR_NOTIN  - probe for all items which are NOT IN @usage;
+ *
+ *  %BLKID_FLTR_ONLYIN - probe for items which are IN @usage
  *
  * Returns: 0 on success, or -1 in case of error.
  */
@@ -699,10 +701,6 @@ int blkid_probe_set_uuid(blkid_probe pr, unsigned char *uuid)
 	return blkid_probe_set_uuid_as(pr, uuid, NULL);
 }
 
-/*
- * DEPRECATED FUNCTIONS
- */
-
 /**
  * blkid_probe_set_request:
  * @pr: probe
@@ -773,3 +771,4 @@ int blkid_probe_filter_usage(blkid_probe pr, int flag, int usage)
 	return blkid_probe_filter_superblocks_usage(pr, flag, usage);
 }
 
+
diff --git a/libblkid/src/superblocks/ubifs.c b/libblkid/src/superblocks/ubifs.c
index 87d94ba2c..2d69c2bf3 100644
--- a/libblkid/src/superblocks/ubifs.c
+++ b/libblkid/src/superblocks/ubifs.c
@@ -12,7 +12,7 @@
 
 #include "superblocks.h"
 
-/**
+/*
  * struct ubifs_ch - common header node.
  * @magic: UBIFS node magic number (%UBIFS_NODE_MAGIC)
  * @crc: CRC-32 checksum of the node header
@@ -35,7 +35,7 @@ struct ubifs_ch {
 	uint8_t padding[2];
 } __attribute__ ((packed));
 
-/**
+/*
  * struct ubifs_sb_node - superblock node.
  * @ch: common header
  * @padding: reserved for future, zeroes
@@ -93,7 +93,6 @@ struct ubifs_sb_node {
 	uint8_t padding2[3968];
 } __attribute__ ((packed));
 
-
 static int probe_ubifs(blkid_probe pr, const struct blkid_idmag *mag)
 {
 	struct ubifs_sb_node *sb;
diff --git a/libblkid/src/topology/topology.c b/libblkid/src/topology/topology.c
index 27dc755fd..d2ac97f8a 100644
--- a/libblkid/src/topology/topology.c
+++ b/libblkid/src/topology/topology.c
@@ -131,9 +131,6 @@ int blkid_probe_enable_topology(blkid_probe pr, int enable)
  *          use more blkid_topopogy objects in the same time you have to create
  *          more blkid_probe handlers (see blkid_new_probe()).
  *
- * TODO:    add blkid_ref() and blkid_unref() to allows to use blkid_topology
- *          independently on libblkid probing stuff.
- *
  * Returns: blkid_topopogy, or NULL in case of error.
  */
 blkid_topology blkid_probe_get_topology(blkid_probe pr)