Fix some doxygen docs warnings and mistakes.

git-svn-id: https://cryptsetup.googlecode.com/svn/trunk@621 36d66b0a-2a48-0410-832c-cd162a569da5
2025-12-11 19:00:02 +01:00 · 2011-10-08 20:27:54 +00:00
parent 7a773f70f3
commit 4e9fa4d2bb
3 changed files with 43 additions and 32 deletions
--- a/Makefile.am
+++ b/Makefile.am
@@ -7,3 +7,6 @@ SUBDIRS = \
 	po

 ACLOCAL_AMFLAGS = -I m4
+
+clean-local:
+	-rm -rf docs/doxygen_api_docs
--- 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
--- 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) */