doc: Unify comment style in gpgme.h

--

Signed-off-by: Werner Koch <wk@gnupg.org>

1 files changed, 175 insertions, 160 deletions

diff --git a/src/gpgme.h.in b/src/gpgme.h.in
index e3a2eea0..84516f91 100644
--- a/src/gpgme.h.in
+++ b/src/gpgme.h.in
@@ -37,14 +37,14 @@ extern "C" {
 
 
 /* The version of this header should match the one of the library.  Do
-   not use this symbol in your application, use gpgme_check_version
-   instead.  The purpose of this macro is to let autoconf (using the
-   AM_PATH_GPGME macro) check that this header matches the installed
-   library.  */
+ * not use this symbol in your application, use gpgme_check_version
+ * instead.  The purpose of this macro is to let autoconf (using the
+ * AM_PATH_GPGME macro) check that this header matches the installed
+ * library.  */
 #define GPGME_VERSION "@PACKAGE_VERSION@"
 
 /* The version number of this header.  It may be used to handle minor
-   API incompatibilities.  */
+ * API incompatibilities.  */
 #define GPGME_VERSION_NUMBER @VERSION_NUMBER@
 
 
@@ -87,7 +87,7 @@ extern "C" {
 
 
 /* The macro _GPGME_DEPRECATED_OUTSIDE_GPGME suppresses warnings for
-   fields we must access in GPGME for ABI compatibility.  */
+ * fields we must access in GPGME for ABI compatibility.  */
 #ifdef _GPGME_IN_GPGME
 #define _GPGME_DEPRECATED_OUTSIDE_GPGME(a,b)
 #else
@@ -113,7 +113,7 @@ extern "C" {
  */
 
 /* The context holds some global state and configuration options, as
-   well as the results of a crypto operation.  */
+ * well as the results of a crypto operation.  */
 struct gpgme_context;
 typedef struct gpgme_context *gpgme_ctx_t;
 
@@ -124,7 +124,8 @@ typedef struct gpgme_data *gpgme_data_t;
 
 
 /*
- * Wrappers for the libgpg-error library.
+ * Wrappers for the libgpg-error library.  They are generally not
+ * needed and the gpg-error versions may be used instead.
  */
 
 typedef gpg_error_t gpgme_error_t;
@@ -140,7 +141,7 @@ gpgme_err_make (gpgme_err_source_t source, gpgme_err_code_t code)
 
 
 /* The user can define GPGME_ERR_SOURCE_DEFAULT before including this
-   file to specify a default source for gpgme_error.  */
+ * file to specify a default source for gpgme_error.  */
 #ifndef GPGME_ERR_SOURCE_DEFAULT
 #define GPGME_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_1
 #endif
@@ -167,45 +168,46 @@ gpgme_err_source (gpgme_error_t err)
 
 
 /* Return a pointer to a string containing a description of the error
-   code in the error value ERR.  This function is not thread safe.  */
+ * code in the error value ERR.  This function is not thread safe.  */
 const char *gpgme_strerror (gpgme_error_t err);
 
 /* Return the error string for ERR in the user-supplied buffer BUF of
-   size BUFLEN.  This function is, in contrast to gpg_strerror,
-   thread-safe if a thread-safe strerror_r() function is provided by
-   the system.  If the function succeeds, 0 is returned and BUF
-   contains the string describing the error.  If the buffer was not
-   large enough, ERANGE is returned and BUF contains as much of the
-   beginning of the error string as fits into the buffer.  */
+ * size BUFLEN.  This function is, in contrast to gpg_strerror,
+ * thread-safe if a thread-safe strerror_r() function is provided by
+ * the system.  If the function succeeds, 0 is returned and BUF
+ * contains the string describing the error.  If the buffer was not
+ * large enough, ERANGE is returned and BUF contains as much of the
+ * beginning of the error string as fits into the buffer.  */
 int gpgme_strerror_r (gpg_error_t err, char *buf, size_t buflen);
 
 /* Return a pointer to a string containing a description of the error
-   source in the error value ERR.  */
+ * source in the error value ERR.  */
 const char *gpgme_strsource (gpgme_error_t err);
 
 /* Retrieve the error code for the system error ERR.  This returns
-   GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
-   this).  */
+ * GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
+ * this).  */
 gpgme_err_code_t gpgme_err_code_from_errno (int err);
 
 /* Retrieve the system error for the error code CODE.  This returns 0
-   if CODE is not a system error code.  */
+ * if CODE is not a system error code.  */
 int gpgme_err_code_to_errno (gpgme_err_code_t code);
 
 /* Retrieve the error code directly from the ERRNO variable.  This
-   returns GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped
-   (report this) and GPG_ERR_MISSING_ERRNO if ERRNO has the value 0. */
+ * returns GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped
+ * (report this) and GPG_ERR_MISSING_ERRNO if ERRNO has the value 0. */
 gpgme_err_code_t gpgme_err_code_from_syserror (void);
 
 /* Set the ERRNO variable.  This function is the preferred way to set
-   ERRNO due to peculiarities on WindowsCE.  */
+ * ERRNO due to peculiarities on WindowsCE.  */
 void gpgme_err_set_errno (int err);
 
 /* Return an error value with the error source SOURCE and the system
-   error ERR.  FIXME: Should be inline.  */
+ *  error ERR.  FIXME: Should be inline.  */
 gpgme_error_t gpgme_err_make_from_errno (gpgme_err_source_t source, int err);
 
-/* Return an error value with the system error ERR.  FIXME: Should be inline.  */
+/* Return an error value with the system error ERR.
+ * inline.  */
 gpgme_error_t gpgme_error_from_errno (int err);
 
 
@@ -419,7 +421,7 @@ struct _gpgme_sig_notation
   struct _gpgme_sig_notation *next;
 
   /* If NAME is a null pointer, then VALUE contains a policy URL
-     rather than a notation.  */
+   * rather than a notation.  */
   char *name;
 
   /* The value of the notation data.  */
@@ -634,10 +636,10 @@ struct _gpgme_key_sig
   /* Same as in gpgme_signature_t.  */
   gpgme_error_t status;
 
+  /* Deprecated; use SIG_CLASS instead.  */
 #ifdef __cplusplus
   unsigned int _obsolete_class _GPGME_DEPRECATED(0,4);
 #else
-  /* Must be set to SIG_CLASS below.  */
   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME(0,4);
 #endif
 
@@ -876,10 +878,10 @@ gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
 
 /* Set the crypto protocol to be used by CTX to PROTO.
-   gpgme_set_protocol actually sets the backend engine.  This sets the
-   crypto protocol used in engines that support more than one crypto
-   prococol (for example, an UISERVER can support OpenPGP and CMS).
-   This is reset to the default with gpgme_set_protocol.  */
+ * gpgme_set_protocol actually sets the backend engine.  This sets the
+ * crypto protocol used in engines that support more than one crypto
+ * prococol (for example, an UISERVER can support OpenPGP and CMS).
+ * This is reset to the default with gpgme_set_protocol.  */
 gpgme_error_t gpgme_set_sub_protocol (gpgme_ctx_t ctx,
 				      gpgme_protocol_t proto);
 
@@ -931,47 +933,47 @@ gpgme_error_t gpgme_set_pinentry_mode (gpgme_ctx_t ctx,
 gpgme_pinentry_mode_t gpgme_get_pinentry_mode (gpgme_ctx_t ctx);
 
 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
-   passed as first argument to the passphrase callback function.  */
+ * passed as first argument to the passphrase callback function.  */
 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
                               gpgme_passphrase_cb_t cb, void *hook_value);
 
 /* Get the current passphrase callback function in *CB and the current
-   hook value in *HOOK_VALUE.  */
+ * hook value in *HOOK_VALUE.  */
 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
 			      void **hook_value);
 
 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
-   passed as first argument to the progress callback function.  */
+ * passed as first argument to the progress callback function.  */
 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
 			    void *hook_value);
 
 /* Get the current progress callback function in *CB and the current
-   hook value in *HOOK_VALUE.  */
+ * hook value in *HOOK_VALUE.  */
 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
 			    void **hook_value);
 
 /* Set the status callback function in CTX to CB.  HOOK_VALUE is
-   passed as first argument to the status callback function.  */
+ * passed as first argument to the status callback function.  */
 void gpgme_set_status_cb (gpgme_ctx_t c, gpgme_status_cb_t cb,
                           void *hook_value);
 
 /* Get the current status callback function in *CB and the current
-   hook value in *HOOK_VALUE.  */
+ * hook value in *HOOK_VALUE.  */
 void gpgme_get_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t *cb,
                           void **hook_value);
 
 /* This function sets the locale for the context CTX, or the default
-   locale if CTX is a null pointer.  */
+ * locale if CTX is a null pointer.  */
 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
 				const char *value);
 
 /* Get the information about the configured engines.  A pointer to the
-   first engine in the statically allocated linked list is returned.
-   The returned data is valid until the next gpgme_ctx_set_engine_info.  */
+ * first engine in the statically allocated linked list is returned.
+ * The returned data is valid until the next gpgme_ctx_set_engine_info.  */
 gpgme_engine_info_t gpgme_ctx_get_engine_info (gpgme_ctx_t ctx);
 
 /* Set the engine info for the context CTX, protocol PROTO, to the
-   file name FILE_NAME and the home directory HOME_DIR.  */
+ * file name FILE_NAME and the home directory HOME_DIR.  */
 gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t ctx,
 					 gpgme_protocol_t proto,
 					 const char *file_name,
@@ -993,10 +995,10 @@ gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
 void gpgme_sig_notation_clear (gpgme_ctx_t ctx);
 
 /* Add the human-readable notation data with name NAME and value VALUE
-   to the context CTX, using the flags FLAGS.  If NAME is NULL, then
-   VALUE should be a policy URL.  The flag
-   GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
-   data, and false for policy URLs.  */
+ * to the context CTX, using the flags FLAGS.  If NAME is NULL, then
+ * VALUE should be a policy URL.  The flag
+ * GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
+ * data, and false for policy URLs.  */
 gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
 				      const char *value,
 				      gpgme_sig_notation_flags_t flags);
@@ -1020,17 +1022,17 @@ const char *gpgme_get_sender (gpgme_ctx_t ctx);
 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
 
 /* The type of a function that can register FNC as the I/O callback
-   function for the file descriptor FD with direction dir (0: for writing,
-   1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
-   function should return a TAG suitable for the corresponding
-   gpgme_remove_io_cb_t, and an error value.  */
+ * function for the file descriptor FD with direction dir (0: for writing,
+ * 1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
+ * function should return a TAG suitable for the corresponding
+ * gpgme_remove_io_cb_t, and an error value.  */
 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
 						 gpgme_io_cb_t fnc,
 						 void *fnc_data, void **tag);
 
 /* The type of a function that can remove a previously registered I/O
-   callback function given TAG as returned by the register
-   function.  */
+ * callback function given TAG as returned by the register
+ * function.  */
 typedef void (*gpgme_remove_io_cb_t) (void *tag);
 
 typedef enum
@@ -1045,7 +1047,7 @@ gpgme_event_io_t;
 struct gpgme_io_event_done_data
 {
   /* A fatal IPC error or an operational error in state-less
-     protocols.  */
+   * protocols.  */
   gpgme_error_t err;
 
   /* An operational errors in session-based protocols.  */
@@ -1054,7 +1056,7 @@ struct gpgme_io_event_done_data
 typedef struct gpgme_io_event_done_data *gpgme_io_event_done_data_t;
 
 /* The type of a function that is called when a context finished an
-   operation.  */
+ * operation.  */
 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
 				     void *type_data);
 
@@ -1075,13 +1077,13 @@ void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
 
 /* Wrappers around the internal I/O functions for use with
-   gpgme_passphrase_cb_t and gpgme_interact_cb_t.  */
+ * gpgme_passphrase_cb_t and gpgme_interact_cb_t.  */
 @API__SSIZE_T@ gpgme_io_read (int fd, void *buffer, size_t count);
 @API__SSIZE_T@ gpgme_io_write (int fd, const void *buffer, size_t count);
 int     gpgme_io_writen (int fd, const void *buffer, size_t count);
 
 /* Process the pending operation and, if HANG is non-zero, wait for
-   the pending operation to finish.  */
+ * the pending operation to finish.  */
 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
 
 gpgme_ctx_t gpgme_wait_ext (gpgme_ctx_t ctx, gpgme_error_t *status,
@@ -1100,21 +1102,21 @@ gpgme_error_t gpgme_cancel_async (gpgme_ctx_t ctx);
  */
 
 /* Read up to SIZE bytes into buffer BUFFER from the data object with
-   the handle HANDLE.  Return the number of characters read, 0 on EOF
-   and -1 on error.  If an error occurs, errno is set.  */
+ * the handle HANDLE.  Return the number of characters read, 0 on EOF
+ * and -1 on error.  If an error occurs, errno is set.  */
 typedef @API__SSIZE_T@ (*gpgme_data_read_cb_t) (void *handle, void *buffer,
 					 size_t size);
 
 /* Write up to SIZE bytes from buffer BUFFER to the data object with
-   the handle HANDLE.  Return the number of characters written, or -1
-   on error.  If an error occurs, errno is set.  */
+ * the handle HANDLE.  Return the number of characters written, or -1
+ * on error.  If an error occurs, errno is set.  */
 typedef @API__SSIZE_T@ (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
 					  size_t size);
 
 /* Set the current position from where the next read or write starts
-   in the data object with the handle HANDLE to OFFSET, relativ to
-   WHENCE.  Returns the new offset in bytes from the beginning of the
-   data object.  */
+ * in the data object with the handle HANDLE to OFFSET, relativ to
+ * WHENCE.  Returns the new offset in bytes from the beginning of the
+ * data object.  */
 typedef @API__OFF_T@ (*gpgme_data_seek_cb_t) (void *handle,
                                        @API__OFF_T@ offset, int whence);
 
@@ -1131,19 +1133,19 @@ struct gpgme_data_cbs
 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
 
 /* Read up to SIZE bytes into buffer BUFFER from the data object with
-   the handle DH.  Return the number of characters read, 0 on EOF and
-   -1 on error.  If an error occurs, errno is set.  */
+ * the handle DH.  Return the number of characters read, 0 on EOF and
+ * -1 on error.  If an error occurs, errno is set.  */
 @API__SSIZE_T@ gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
 
 /* Write up to SIZE bytes from buffer BUFFER to the data object with
-   the handle DH.  Return the number of characters written, or -1 on
-   error.  If an error occurs, errno is set.  */
+ * the handle DH.  Return the number of characters written, or -1 on
+ * error.  If an error occurs, errno is set.  */
 @API__SSIZE_T@ gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
 
 /* Set the current position from where the next read or write starts
-   in the data object with the handle DH to OFFSET, relativ to WHENCE.
-   Returns the new offset in bytes from the beginning of the data
-   object.  */
+ * in the data object with the handle DH to OFFSET, relativ to WHENCE.
+ * Returns the new offset in bytes from the beginning of the data
+ * object.  */
 @API__OFF_T@ gpgme_data_seek (gpgme_data_t dh, @API__OFF_T@ offset, int whence);
 
 /* Create a new data buffer and return it in R_DH.  */
@@ -1153,19 +1155,19 @@ gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
 void gpgme_data_release (gpgme_data_t dh);
 
 /* Create a new data buffer filled with SIZE bytes starting from
-   BUFFER.  If COPY is zero, copying is delayed until necessary, and
-   the data is taken from the original location when needed.  */
+ * BUFFER.  If COPY is zero, copying is delayed until necessary, and
+ * the data is taken from the original location when needed.  */
 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
 				       const char *buffer, size_t size,
 				       int copy);
 
 /* Destroy the data buffer DH and return a pointer to its content.
-   The memory has be to released with gpgme_free() by the user.  It's
-   size is returned in R_LEN.  */
+ * The memory has be to released with gpgme_free() by the user.  It's
+ * size is returned in R_LEN.  */
 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
 
 /* Release the memory returned by gpgme_data_release_and_get_mem() and
-   some other functions.  */
+ * some other functions.  */
 void gpgme_free (void *buffer);
 
 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
@@ -1184,11 +1186,11 @@ gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
 				       gpgme_data_encoding_t enc);
 
 /* Get the file name associated with the data object with handle DH, or
-   NULL if there is none.  */
+ * NULL if there is none.  */
 char *gpgme_data_get_file_name (gpgme_data_t dh);
 
 /* Set the file name associated with the data object with handle DH to
-   FILE_NAME.  */
+ * FILE_NAME.  */
 gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh,
 					const char *file_name);
 
@@ -1201,15 +1203,15 @@ gpgme_data_type_t gpgme_data_identify (gpgme_data_t dh, int reserved);
 
 
 /* Create a new data buffer filled with the content of file FNAME.
-   COPY must be non-zero.  For delayed read, please use
-   gpgme_data_new_from_fd or gpgme_data_new_from_stream instead.  */
+ * COPY must be non-zero.  For delayed read, please use
+ * gpgme_data_new_from_fd or gpgme_data_new_from_stream instead.  */
 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
 					const char *fname,
 					int copy);
 
 /* Create a new data buffer filled with LENGTH bytes starting from
-   OFFSET within the file FNAME or stream FP (exactly one must be
-   non-zero).  */
+ * OFFSET within the file FNAME or stream FP (exactly one must be
+ * non-zero).  */
 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
 					    const char *fname, FILE *fp,
 					    @API__OFF_T@ offset, size_t length);
@@ -1224,7 +1226,7 @@ gpgme_error_t gpgme_data_rewind (gpgme_data_t dh);
  */
 
 /* Get the key with the fingerprint FPR from the crypto backend.  If
-   SECRET is true, get the secret key.  */
+ * SECRET is true, get the secret key.  */
 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
 			     gpgme_key_t *r_key, int secret);
 
@@ -1235,7 +1237,7 @@ gpgme_error_t gpgme_key_from_uid (gpgme_key_t *key, const char *name);
 void gpgme_key_ref (gpgme_key_t key);
 
 /* Release a reference to KEY.  If this was the last one the key is
-   destroyed.  */
+ * destroyed.  */
 void gpgme_key_unref (gpgme_key_t key);
 void gpgme_key_release (gpgme_key_t key);
 
@@ -1274,7 +1276,7 @@ typedef enum
 gpgme_encrypt_flags_t;
 
 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
-   store the resulting ciphertext in CIPHER.  */
+ * store the resulting ciphertext in CIPHER.  */
 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
 				      gpgme_encrypt_flags_t flags,
 				      gpgme_data_t plain,
@@ -1295,8 +1297,8 @@ gpgme_error_t gpgme_op_encrypt_ext (gpgme_ctx_t ctx, gpgme_key_t recp[],
                                     gpgme_data_t cipher);
 
 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
-   store the resulting ciphertext in CIPHER.  Also sign the ciphertext
-   with the signers in CTX.  */
+ * store the resulting ciphertext in CIPHER.  Also sign the ciphertext
+ * with the signers in CTX.  */
 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
 					   gpgme_key_t recp[],
 					   gpgme_encrypt_flags_t flags,
@@ -1344,6 +1346,7 @@ struct _gpgme_recipient
 };
 typedef struct _gpgme_recipient *gpgme_recipient_t;
 
+
 /* An object to return results from a decryption operation.
  * This structure shall be considered read-only and an application
  * must not allocate such a structure on its own.  */
@@ -1367,22 +1370,24 @@ struct _gpgme_op_decrypt_result
   gpgme_recipient_t recipients;
 
   /* The original file name of the plaintext message, if
-     available.  */
+   * available.  */
   char *file_name;
 
   /* A textual representation of the session key used to decrypt the
    * message, if available */
   char *session_key;
 
-   /* A string with the symmetric encryption algorithm and mode using
-    * the format "<algo>.<mode>".  */
+  /* A string with the symmetric encryption algorithm and mode using
+   * the format "<algo>.<mode>".  */
   char *symkey_algo;
 };
 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
 
+
 /* Retrieve a pointer to the result of the decrypt operation.  */
 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
 
+
 /* The valid decryption flags.  */
 typedef enum
   {
@@ -1391,15 +1396,16 @@ typedef enum
   }
 gpgme_decrypt_flags_t;
 
+
 /* Decrypt ciphertext CIPHER within CTX and store the resulting
-   plaintext in PLAIN.  */
+ * plaintext in PLAIN.  */
 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
 				      gpgme_data_t plain);
 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
 				gpgme_data_t cipher, gpgme_data_t plain);
 
 /* Decrypt ciphertext CIPHER and make a signature verification within
-   CTX and store the resulting plaintext in PLAIN.  */
+ * CTX and store the resulting plaintext in PLAIN.  */
 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
 					     gpgme_data_t cipher,
 					     gpgme_data_t plain);
@@ -1441,7 +1447,7 @@ struct _gpgme_new_signature
   gpgme_hash_algo_t hash_algo;
 
   /* Internal to GPGME, do not use.  Must be set to the same value as
-     CLASS below.  */
+   * CLASS below.  */
   unsigned long _obsolete_class;
 
   /* Signature creation time.  */
@@ -1450,10 +1456,10 @@ struct _gpgme_new_signature
   /* The fingerprint of the signature.  */
   char *fpr;
 
+  /* Deprecated; use SIG_CLASS instead.  */
 #ifdef __cplusplus
   unsigned int _obsolete_class_2;
 #else
-  /* Must be set to SIG_CLASS below.  */
   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME(0,4);
 #endif
 
@@ -1474,6 +1480,7 @@ struct _gpgme_op_sign_result
 };
 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
 
+
 /* Retrieve a pointer to the result of the signing operation.  */
 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
 
@@ -1567,6 +1574,7 @@ struct _gpgme_signature
 };
 typedef struct _gpgme_signature *gpgme_signature_t;
 
+
 /* An object to return the results of a verify operation.
  * This structure shall be considered read-only and an application
  * must not allocate such a structure on its own.  */
@@ -1586,6 +1594,7 @@ struct _gpgme_op_verify_result
 };
 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
 
+
 /* Retrieve a pointer to the result of the verify operation.  */
 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
 
@@ -1630,6 +1639,7 @@ struct _gpgme_import_status
 };
 typedef struct _gpgme_import_status *gpgme_import_status_t;
 
+
 /* Import result object.
  * This structure shall be considered read-only and an application
  * must not allocate such a structure on its own.  */
@@ -1685,6 +1695,7 @@ struct _gpgme_op_import_result
 };
 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
 
+
 /* Retrieve a pointer to the result of the import operation.  */
 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
 
@@ -1742,6 +1753,7 @@ gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t ctx,
 #define GPGME_CREATE_FORCE      (1 << 12) /* Force creation.           */
 #define GPGME_CREATE_NOEXPIRE   (1 << 13) /* Create w/o expiration.    */
 
+
 /* An object to return result from a key generation.
  * This structure shall be considered read-only and an application
  * must not allocate such a structure on its own.  */
@@ -1772,9 +1784,10 @@ struct _gpgme_op_genkey_result
 };
 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
 
+
 /* Generate a new keypair and add it to the keyring.  PUBKEY and
-   SECKEY should be null for now.  PARMS specifies what keys should be
-   generated.  */
+ * SECKEY should be null for now.  PARMS specifies what keys should be
+ * generated.  */
 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
 				     gpgme_data_t pubkey, gpgme_data_t seckey);
 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
@@ -1840,7 +1853,7 @@ gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
 
 
 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
-   keys are also deleted.  */
+ * keys are also deleted.  */
 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
 				     int allow_secret);
 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
@@ -1959,7 +1972,7 @@ gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
  */
 
 /* Change the passphrase for KEY.  FLAGS is reserved for future use
-   and must be passed as 0.  */
+ * and must be passed as 0.  */
 gpgme_error_t gpgme_op_passwd_start (gpgme_ctx_t ctx, gpgme_key_t key,
                                      unsigned int flags);
 gpgme_error_t gpgme_op_passwd (gpgme_ctx_t ctx, gpgme_key_t key,
@@ -2024,7 +2037,7 @@ gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
 void gpgme_trust_item_ref (gpgme_trust_item_t item);
 
 /* Release a reference to ITEM.  If this was the last one the trust
-   item is destroyed.  */
+ * item is destroyed.  */
 void gpgme_trust_item_unref (gpgme_trust_item_t item);
 
 
@@ -2054,8 +2067,8 @@ gpgme_error_t gpgme_op_getauditlog (gpgme_ctx_t ctx, gpgme_data_t output,
 
 
 /* Run the command FILE with the arguments in ARGV.  Connect stdin to
-   DATAIN, stdout to DATAOUT, and STDERR to DATAERR.  If one the data
-   streams is NULL, connect to /dev/null instead.  */
+ * DATAIN, stdout to DATAOUT, and STDERR to DATAERR.  If one the data
+ * streams is NULL, connect to /dev/null instead.  */
 gpgme_error_t gpgme_op_spawn_start (gpgme_ctx_t ctx,
                                     const char *file, const char *argv[],
                                     gpgme_data_t datain,
@@ -2071,6 +2084,7 @@ gpgme_error_t gpgme_op_spawn (gpgme_ctx_t ctx,
 /*
  * Low-level Assuan protocol access.
  */
+
 typedef gpgme_error_t (*gpgme_assuan_data_cb_t)
      (void *opaque, const void *data, size_t datalen);
 
@@ -2082,7 +2096,7 @@ typedef gpgme_error_t (*gpgme_assuan_status_cb_t)
      (void *opaque, const char *status, const char *args);
 
 /* Send the Assuan COMMAND and return results via the callbacks.
-   Asynchronous variant. */
+ * Asynchronous variant. */
 gpgme_error_t gpgme_op_assuan_transact_start (gpgme_ctx_t ctx,
                                               const char *command,
                                               gpgme_assuan_data_cb_t data_cb,
@@ -2093,7 +2107,7 @@ gpgme_error_t gpgme_op_assuan_transact_start (gpgme_ctx_t ctx,
                                               void *stat_cb_value);
 
 /* Send the Assuan COMMAND and return results via the callbacks.
-   Synchronous variant. */
+ * Synchronous variant. */
 gpgme_error_t gpgme_op_assuan_transact_ext (gpgme_ctx_t ctx,
 					    const char *command,
 					    gpgme_assuan_data_cb_t data_cb,
@@ -2121,8 +2135,8 @@ typedef struct _gpgme_op_vfs_mount_result *gpgme_vfs_mount_result_t;
 gpgme_vfs_mount_result_t gpgme_op_vfs_mount_result (gpgme_ctx_t ctx);
 
 /* The container is automatically unmounted when the context is reset
-   or destroyed.  Transmission errors are returned directly,
-   operational errors are returned in OP_ERR.  */
+ * or destroyed.  Transmission errors are returned directly,
+ * operational errors are returned in OP_ERR.  */
 gpgme_error_t gpgme_op_vfs_mount (gpgme_ctx_t ctx, const char *container_file,
 				  const char *mount_dir, unsigned int flags,
 				  gpgme_error_t *op_err);
@@ -2137,8 +2151,8 @@ gpgme_error_t gpgme_op_vfs_create (gpgme_ctx_t ctx, gpgme_key_t recp[],
  */
 
 /* The expert level at which a configuration option or group of
-   options should be displayed.  See the gpgconf(1) documentation for
-   more details.  */
+ * options should be displayed.  See the gpgconf(1) documentation for
+ * more details.  */
 typedef enum
   {
     GPGME_CONF_BASIC = 0,
@@ -2151,7 +2165,7 @@ gpgme_conf_level_t;
 
 
 /* The data type of a configuration option argument.  See the gpgconf(1)
-   documentation for more details.  */
+ * documentation for more details.  */
 typedef enum
   {
     /* Basic types.  */
@@ -2175,7 +2189,7 @@ gpgme_conf_type_t;
 
 
 /* This represents a single argument for a configuration option.
-   Which of the members of value is used depends on the ALT_TYPE.  */
+ * Which of the members of value is used depends on the ALT_TYPE.  */
 typedef struct gpgme_conf_arg
 {
   struct gpgme_conf_arg *next;
@@ -2192,7 +2206,7 @@ typedef struct gpgme_conf_arg
 
 
 /* The flags of a configuration option.  See the gpgconf
-   documentation for details.  */
+ * documentation for details.  */
 #define GPGME_CONF_GROUP	(1 << 0)
 #define GPGME_CONF_OPTIONAL	(1 << 1)
 #define GPGME_CONF_LIST		(1 << 2)
@@ -2204,7 +2218,7 @@ typedef struct gpgme_conf_arg
 
 
 /* The representation of a single configuration option.  See the
-   gpg-conf documentation for details.  */
+ * gpg-conf documentation for details.  */
 typedef struct gpgme_conf_opt
 {
   struct gpgme_conf_opt *next;
@@ -2249,7 +2263,7 @@ typedef struct gpgme_conf_opt
 
 
 /* The representation of a component that can be configured.  See the
-   gpg-conf documentation for details.  */
+ * gpg-conf documentation for details.  */
 typedef struct gpgme_conf_comp
 {
   struct gpgme_conf_comp *next;
@@ -2272,9 +2286,9 @@ typedef struct gpgme_conf_comp
 
 
 /* Allocate a new gpgme_conf_arg_t.  If VALUE is NULL, a "no arg
-   default" is prepared.  If type is a string type, VALUE should point
-   to the string.  Else, it should point to an unsigned or signed
-   integer respectively.  */
+ * default" is prepared.  If type is a string type, VALUE should point
+ * to the string.  Else, it should point to an unsigned or signed
+ * integer respectively.  */
 gpgme_error_t gpgme_conf_arg_new (gpgme_conf_arg_t *arg_p,
 				  gpgme_conf_type_t type, const void *value);
 
@@ -2282,10 +2296,10 @@ gpgme_error_t gpgme_conf_arg_new (gpgme_conf_arg_t *arg_p,
 void gpgme_conf_arg_release (gpgme_conf_arg_t arg, gpgme_conf_type_t type);
 
 /* Register a change for the value of OPT to ARG.  If RESET is 1 (do
-   not use any values but 0 or 1), ARG is ignored and the option is
-   not changed (reverting a previous change).  Otherwise, if ARG is
-   NULL, the option is cleared or reset to its default. The change
-   is done with gpgconf's --runtime option to immediately take effect. */
+ * not use any values but 0 or 1), ARG is ignored and the option is
+ * not changed (reverting a previous change).  Otherwise, if ARG is
+ * NULL, the option is cleared or reset to its default. The change
+ * is done with gpgconf's --runtime option to immediately take effect. */
 gpgme_error_t gpgme_conf_opt_change (gpgme_conf_opt_t opt, int reset,
 				     gpgme_conf_arg_t arg);
 
@@ -2376,16 +2390,17 @@ gpgme_query_swdb_result_t gpgme_op_query_swdb_result (gpgme_ctx_t ctx);
 int gpgme_set_global_flag (const char *name, const char *value);
 
 /* Check that the library fulfills the version requirement.  Note:
-   This is here only for the case where a user takes a pointer from
-   the old version of this function.  The new version and macro for
-   run-time checks are below.  */
+ * This is here only for the case where a user takes a pointer from
+ * the old version of this function.  The new version and macro for
+ * run-time checks are below.  */
 const char *gpgme_check_version (const char *req_version);
 
-/* Check that the library fulfills the version requirement and check
-   for struct layout mismatch involving bitfields.  */
+/* Do not call this directly; use the macro below.  */
 const char *gpgme_check_version_internal (const char *req_version,
 					  size_t offset_sig_validity);
 
+/* Check that the library fulfills the version requirement and check
+ * for struct layout mismatch involving bitfields.  */
 #define gpgme_check_version(req_version)				\
   gpgme_check_version_internal (req_version,				\
 				offsetof (struct _gpgme_signature, validity))
@@ -2394,19 +2409,19 @@ const char *gpgme_check_version_internal (const char *req_version,
 const char *gpgme_get_dirinfo (const char *what);
 
 /* Get the information about the configured and installed engines.  A
-   pointer to the first engine in the statically allocated linked list
-   is returned in *INFO.  If an error occurs, it is returned.  The
-   returned data is valid until the next gpgme_set_engine_info.  */
+ * pointer to the first engine in the statically allocated linked list
+ * is returned in *INFO.  If an error occurs, it is returned.  The
+ * returned data is valid until the next gpgme_set_engine_info.  */
 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
 
 /* Set the default engine info for the protocol PROTO to the file name
-   FILE_NAME and the home directory HOME_DIR.  */
+ * FILE_NAME and the home directory HOME_DIR.  */
 gpgme_error_t gpgme_set_engine_info (gpgme_protocol_t proto,
 				     const char *file_name,
 				     const char *home_dir);
 
 /* Verify that the engine implementing PROTO is installed and
-   available.  */
+ * available.  */
 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
 
 
@@ -2415,15 +2430,15 @@ void gpgme_result_ref (void *result);
 void gpgme_result_unref (void *result);
 
 /* Return a public key algorithm string (e.g. "rsa2048").  Caller must
-   free using gpgme_free.  */
+ * free using gpgme_free.  */
 char *gpgme_pubkey_algo_string (gpgme_subkey_t subkey);
 
 /* Return a statically allocated string with the name of the public
-   key algorithm ALGO, or NULL if that name is not known.  */
+ * key algorithm ALGO, or NULL if that name is not known.  */
 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
 
 /* Return a statically allocated string with the name of the hash
-   algorithm ALGO, or NULL if that name is not known.  */
+ * algorithm ALGO, or NULL if that name is not known.  */
 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
 
 /* Return the addr-spec from a user id.  Caller must free the result
@@ -2575,7 +2590,7 @@ gpgme_error_t gpgme_op_card_edit       (gpgme_ctx_t ctx, gpgme_key_t key,
                                         _GPGME_DEPRECATED(1,7);
 
 /* The possible signature stati.  Deprecated, use error value in sig
-   status.  */
+ * status.  */
 typedef enum
   {
     GPGME_SIG_STAT_NONE  = 0,
@@ -2592,7 +2607,7 @@ _gpgme_sig_stat_t;
 typedef _gpgme_sig_stat_t gpgme_sig_stat_t _GPGME_DEPRECATED(0,4);
 
 /* The available key and signature attributes.  Deprecated, use the
-   individual result structures instead.  */
+ * individual result structures instead.  */
 typedef enum
   {
     GPGME_ATTR_KEYID        = 1,
@@ -2632,18 +2647,18 @@ _gpgme_attr_t;
 typedef _gpgme_attr_t gpgme_attr_t _GPGME_DEPRECATED(0,4);
 
 /* Retrieve the signature status of signature IDX in CTX after a
-   successful verify operation in R_STAT (if non-null).  The creation
-   time stamp of the signature is returned in R_CREATED (if non-null).
-   The function returns a string containing the fingerprint.
-   Deprecated, use verify result directly.  */
+ * successful verify operation in R_STAT (if non-null).  The creation
+ * time stamp of the signature is returned in R_CREATED (if non-null).
+ * The function returns a string containing the fingerprint.
+ * Deprecated, use verify result directly.  */
 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
                                   _gpgme_sig_stat_t *r_stat,
 				  time_t *r_created) _GPGME_DEPRECATED(0,4);
 
 /* Retrieve certain attributes of a signature.  IDX is the index
-   number of the signature after a successful verify operation.  WHAT
-   is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
-   one.  WHATIDX is to be passed as 0 for most attributes . */
+ * number of the signature after a successful verify operation.  WHAT
+ * is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
+ * one.  WHATIDX is to be passed as 0 for most attributes . */
 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
                                         _gpgme_attr_t what, int whatidx)
      _GPGME_DEPRECATED(0,4);
@@ -2653,13 +2668,13 @@ const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
 
 
 /* Get the key used to create signature IDX in CTX and return it in
-   R_KEY.  */
+ * R_KEY.  */
 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
      _GPGME_DEPRECATED(0,4);
 
 /* Create a new data buffer which retrieves the data from the callback
-   function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
-   instead.  */
+ * function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
+ * instead.  */
 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
 					   int (*read_cb) (void*,char *,
 							   size_t,size_t*),
@@ -2667,34 +2682,34 @@ gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
      _GPGME_DEPRECATED(0,4);
 
 /* Return the value of the attribute WHAT of KEY, which has to be
-   representable by a string.  IDX specifies the sub key or user ID
-   for attributes related to sub keys or user IDs.  Deprecated, use
-   key structure directly instead. */
+ * representable by a string.  IDX specifies the sub key or user ID
+ * for attributes related to sub keys or user IDs.  Deprecated, use
+ * key structure directly instead. */
 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
 				       const void *reserved, int idx)
      _GPGME_DEPRECATED(0,4);
 
 /* Return the value of the attribute WHAT of KEY, which has to be
-   representable by an unsigned integer.  IDX specifies the sub key or
-   user ID for attributes related to sub keys or user IDs.
-   Deprecated, use key structure directly instead.  */
+ * representable by an unsigned integer.  IDX specifies the sub key or
+ * user ID for attributes related to sub keys or user IDs.
+ * Deprecated, use key structure directly instead.  */
 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
 					const void *reserved, int idx)
      _GPGME_DEPRECATED(0,4);
 
 /* Return the value of the attribute WHAT of a signature on user ID
-   UID_IDX in KEY, which has to be representable by a string.  IDX
-   specifies the signature.  Deprecated, use key structure directly
-   instead.  */
+ * UID_IDX in KEY, which has to be representable by a string.  IDX
+ * specifies the signature.  Deprecated, use key structure directly
+ * instead.  */
 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
 					   _gpgme_attr_t what,
 					   const void *reserved, int idx)
      _GPGME_DEPRECATED(0,4);
 
 /* Return the value of the attribute WHAT of a signature on user ID
-   UID_IDX in KEY, which has to be representable by an unsigned
-   integer string.  IDX specifies the signature.  Deprecated, use key
-   structure directly instead.  */
+ * UID_IDX in KEY, which has to be representable by an unsigned
+ * integer string.  IDX specifies the signature.  Deprecated, use key
+ * structure directly instead.  */
 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
 					    _gpgme_attr_t what,
 					    const void *reserved, int idx)
@@ -2705,21 +2720,21 @@ gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
 				   int *nr) _GPGME_DEPRECATED(0,4);
 
 /* Release the trust item ITEM.  Deprecated, use
-   gpgme_trust_item_unref.  */
+ * gpgme_trust_item_unref.  */
 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED(0,4);
 
 /* Return the value of the attribute WHAT of ITEM, which has to be
-   representable by a string.  Deprecated, use trust item structure
-   directly.  */
+ * representable by a string.  Deprecated, use trust item structure
+ * directly.  */
 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
 					      _gpgme_attr_t what,
 					      const void *reserved, int idx)
      _GPGME_DEPRECATED(0,4);
 
 /* Return the value of the attribute WHAT of KEY, which has to be
-   representable by an integer.  IDX specifies a running index if the
-   attribute appears more than once in the key.  Deprecated, use trust
-   item structure directly.  */
+ * representable by an integer.  IDX specifies a running index if the
+ * attribute appears more than once in the key.  Deprecated, use trust
+ * item structure directly.  */
 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
 				   const void *reserved, int idx)
      _GPGME_DEPRECATED(0,4);