Fix some doxygen docs warnings and mistakes.

git-svn-id: https://cryptsetup.googlecode.com/svn/trunk@621 36d66b0a-2a48-0410-832c-cd162a569da5

diff --git a/Makefile.am b/Makefile.am
index a3ff5b3..58dcc9c 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -7,3 +7,6 @@ SUBDIRS = \
        po
 
 ACLOCAL_AMFLAGS = -I m4
+
+clean-local:
+       -rm -rf docs/doxygen_api_docs

diff --git a/docs/doxygen_index b/docs/doxygen_index
index aa004f8..eff8a57 100644 (file)
--- a/docs/doxygen_index
+++ b/docs/doxygen_index
@@ -5,25 +5,25 @@
  * the examples that describe some features of cryptsetup API.
  *
  * <OL type="A">
- *     <LI>@ref cexamples "Cryptsetup API examples" @endref</LI>
+ *     <LI>@ref cexamples "Cryptsetup API examples"</LI>
  *     <OL type="1">
- *             <LI>@ref cluks "crypt_luks_usage" @endref - cryptsetup LUKS device type usage examples</LI>
+ *             <LI>@ref cluks "crypt_luks_usage" - cryptsetup LUKS device type usage examples</LI>
  *                     <UL>
- *                             <LI>@ref cinit "crypt_init()" @endref</LI>
- *                             <LI>@ref cformat "crypt_format()" @endref - header and payload on mutual device</LI>
- *                             <LI>@ref ckeys "Keyslot operations" @endref </LI>
+ *                             <LI>@ref cinit "crypt_init()"</LI>
+ *                             <LI>@ref cformat "crypt_format()" - header and payload on mutual device</LI>
+ *                             <LI>@ref ckeys "Keyslot operations" </LI>
  *                             <UL>
- *                                     <LI>@ref ckeyslot_vol "crypt_keyslot_add_by_volume_key()" @endref</LI>
- *                                     <LI>@ref ckeyslot_pass "crypt_keyslot_add_by_passphrase()" @endref</LI>
+ *                                     <LI>@ref ckeyslot_vol "crypt_keyslot_add_by_volume_key()"</LI>
+ *                                     <LI>@ref ckeyslot_pass "crypt_keyslot_add_by_passphrase()"</LI>
  *                             </UL>
- *                             <LI>@ref cload "crypt_load() @endref"
- *                             <LI>@ref cactivate "crypt_activate_by_passphrase()" @endref</LI>
- *                             <LI>@ref cactive_pars "crypt_get_active_device()" @endref</LI>
- *                             <LI>@ref cinit_by_name "crypt_init_by_name()" @endref</LI>
- *                             <LI>@ref cdeactivate "crypt_deactivate()" @endref</LI>
- *                             <LI>@ref cluks_ex "crypt_luks_usage.c" @endref</LI>
+ *                             <LI>@ref cload "crypt_load()"
+ *                             <LI>@ref cactivate "crypt_activate_by_passphrase()"</LI>
+ *                             <LI>@ref cactive_pars "crypt_get_active_device()"</LI>
+ *                             <LI>@ref cinit_by_name "crypt_init_by_name()"</LI>
+ *                             <LI>@ref cdeactivate "crypt_deactivate()"</LI>
+ *                             <LI>@ref cluks_ex "crypt_luks_usage.c"</LI>
  *                     </UL>
- *             <LI>@ref clog "crypt_log_usage" @endref - cryptsetup logging API examples</LI>
+ *             <LI>@ref clog "crypt_log_usage" - cryptsetup logging API examples</LI>
  *     </OL>
  * </OL>
  *
@@ -33,7 +33,7 @@
  *
  *                     Every time you need to do something with cryptsetup or dmcrypt device
  *                     you need a valid context. The first step to start your work is
- *                     @ref crypt_init @endref call. You can call it either with path
+ *                     @ref crypt_init call. You can call it either with path
  *                     to the block device or path to the regular file. If you don't supply the path,
  *                     empty context is initialized.
  *
@@ -45,12 +45,12 @@
  *                     are both stored on the same device. There's also a possibility to store header and
  *                     data separately.
  *
- *                     <B>Bear in mind</B> that @ref crypt_format() @endref is destructive operation and it
+ *                     <B>Bear in mind</B> that @ref crypt_format() is destructive operation and it
  *                     overwrites part of the backing block device.
  *
  *             @subsection ckeys Keyslot operations examples
  *
- *                     After successful @ref crypt_format @endref of LUKS device, volume key is not stored
+ *                     After successful @ref crypt_format of LUKS device, volume key is not stored
  *                     in a persistent way on the device. Keyslot area is an array beyond LUKS header, where
  *                     volume key is stored in the encrypted form using user input passphrase. For more info about
  *                     LUKS keyslots and how it's actually protected, please look at

diff --git a/lib/libcryptsetup.h b/lib/libcryptsetup.h
index 95d6be5..897fd64 100644 (file)
--- a/lib/libcryptsetup.h
+++ b/lib/libcryptsetup.h
@@ -3,7 +3,7 @@
  * @brief Public cryptsetup API
  *
  * For more verbose examples of LUKS related use cases,
- * please read @ref index "examples" @endref.
+ * please read @ref index "examples".
  */
 
 #ifndef _LIBCRYPTSETUP_H
@@ -65,7 +65,7 @@ int crypt_init_by_name_and_header(struct crypt_device **cd,
 int crypt_init_by_name(struct crypt_device **cd, const char *name);
 
 /**
- * @defgroup loglevel "Cryptsetup logging API"
+ * @defgroup loglevel "Cryptsetup logging"
  *
  * Set of functions and defines used in cryptsetup for
  * logging purposes
@@ -141,6 +141,7 @@ void crypt_set_confirm_callback(struct crypt_device *cd,
  * or negative errno value in case of error.
  *
  * @param cd crypt device handle
+ * @param password user defined password callback reference
  * @param usrptr provided identification in callback
  * @param msg Message for user
  * @param buf buffer for password
@@ -183,7 +184,7 @@ void crypt_set_timeout(struct crypt_device *cd, uint64_t timeout_sec);
 void crypt_set_password_retry(struct crypt_device *cd, int tries);
 
 /**
- * Set how long should cryptsetup iterate in PBKDF2 pseudorandom function.
+ * Set how long should cryptsetup iterate in PBKDF2 function.
  * Default value heads towards the iterations which takes around 1 second
  *
  * @param cd crypt device handle
@@ -207,13 +208,13 @@ void crypt_set_password_verify(struct crypt_device *cd, int password_verify);
  * @param device path to device
  *
  * @pre context is of LUKS type
- * @pre unlike @ref crypt_init @endref, in this function param @e device
+ * @pre unlike @ref crypt_init, in this function param @e device
  *     has to be block device (at least 512B large)
  */
 int crypt_set_data_device(struct crypt_device *cd, const char *device);
 
 /**
- * @defgroup rng "Cryptsetup (pseudo)random API"
+ * @defgroup rng "Cryptsetup RNG"
  *
  * @addtogroup rng
  * @{
@@ -442,7 +443,7 @@ int crypt_resume_by_passphrase(struct crypt_device *cd,
  * @param name name of device to resume
  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
  * @param keyfile key file used to unlock volume key, @e NULL for passphrase query
- * @param keyfile_size number of bytes to read from @keyfile, 0 is unlimited
+ * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
  *
  * @return unlocked key slot number or negative errno otherwise.
  */
@@ -460,7 +461,7 @@ int crypt_resume_by_keyfile(struct crypt_device *cd,
 void crypt_free(struct crypt_device *cd);
 
 /**
- * @defgroup keyslot "Cryptsetup LUKS keyslots API"
+ * @defgroup keyslot "Cryptsetup LUKS keyslots"
  * @addtogroup keyslot
  * @{
  *
@@ -477,7 +478,7 @@ void crypt_free(struct crypt_device *cd);
  * @param cd crypt device handle
  * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
  * @param passphrase passphrase used to unlock volume key, @e NULL for query
- * @param passphrase_size size of @passphrase (binary data)
+ * @param passphrase_size size of passphrase (binary data)
  * @param new_passphrase passphrase for new keyslot, @e NULL for query
  * @param new_passphrase_size size of @e new_passphrase (binary data)
  *
@@ -508,7 +509,7 @@ int crypt_keyslot_max(const char *type);
  * @param cd crypt device handle
  * @param keyslot requested keyslot or @e CRYPT_ANY_SLOT
  * @param keyfile key file used to unlock volume key, @e NULL for passphrase query
- * @param keyfile_size number of bytes to read from @keyfile, @e 0 is unlimited
+ * @param keyfile_size number of bytes to read from keyfile, @e 0 is unlimited
  * @param new_keyfile keyfile for new keyslot, @e NULL for passphrase query
  * @param new_keyfile_size number of bytes to read from @e new_keyfile, @e 0 is unlimited
  *
@@ -532,9 +533,9 @@ int crypt_keyslot_add_by_keyfile(struct crypt_device *cd,
  * @param cd crypt device handle
  * @param keyslot requested keyslot or CRYPT_ANY_SLOT
  * @param volume_key provided volume key or @e NULL if used after crypt_format
- * @param volume_key_size size of @volume_key
+ * @param volume_key_size size of volume_key
  * @param passphrase passphrase for new keyslot, @e NULL for query
- * @param passphrase_size size of @passphrase
+ * @param passphrase_size size of passphrase
  *
  * @return allocated key slot number or negative errno otherwise.
  *
@@ -632,7 +633,7 @@ int crypt_activate_by_passphrase(struct crypt_device *cd,
  * @param name name of device to create, if @e NULL only check keyfile
  * @param keyslot requested keyslot to check or CRYPT_ANY_SLOT
  * @param keyfile key file used to unlock volume key
- * @param keyfile_size number of bytes to read from @keyfile, 0 is unlimited
+ * @param keyfile_size number of bytes to read from keyfile, 0 is unlimited
  * @param flags activation flags
  *
  * @return unlocked key slot number or negative errno otherwise.
@@ -651,14 +652,14 @@ int crypt_activate_by_keyfile(struct crypt_device *cd,
  * @param cd crypt device handle
  * @param name name of device to create, if @e NULL only check volume key
  * @param volume_key provided volume key (or @e NULL to use internal)
- * @param volume_key_size size of @volume_key
+ * @param volume_key_size size of volume_key
  * @param flags activation flags
  *
  * @return @e 0 on success or negative errno value otherwise.
  *
  * @note If @e NULL is used for volume_key, device has to be initialized
- *      by previous operation (like @ref crypt_format @endref
- *      or @ref crypt_init_by_name @endref)
+ *      by previous operation (like @ref crypt_format
+ *      or @ref crypt_init_by_name)
  */
 int crypt_activate_by_volume_key(struct crypt_device *cd,
        const char *name,
@@ -719,6 +720,9 @@ int crypt_volume_key_verify(struct crypt_device *cd,
  * @{
  */
 
+/**
+ * Device status
+ */
 typedef enum {
        CRYPT_INVALID, /**< device mapping is invalid in this context */
        CRYPT_INACTIVE, /**< no such mapped device */
@@ -821,6 +825,10 @@ int crypt_get_volume_key_size(struct crypt_device *cd);
  * @{
  *
  */
+
+/**
+ * Crypt keyslot info
+ */
 typedef enum {
        CRYPT_SLOT_INVALID, /**< invalid keyslot */
        CRYPT_SLOT_INACTIVE, /**< keyslot is inactive (free) */