From: Marcus Brinkmann <mb@g10code.com>
Date: Wed, 30 Jan 2002 01:17:30 +0000 (+0000)
Subject: doc/
X-Git-Tag: gpgme-0-3-1~31
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=785991aa9ac6c2c7ba994fcb69f988ad21016df2;p=gpgme.git

doc/
2002-01-30  Marcus Brinkmann  <marcus@g10code.de>

	* gpgme.texi: Add all the gpgme_op_*_start functions.
	Fill the concept index with many, many entries.

gpgme/
2002-01-30  Marcus Brinkmann  <marcus@g10code.de>

	* gpgme.h: Add lots of comment and fix the formatting.  Add
	gpgme_trustlist_end prototype.
---

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 7c3eee7..61320d4 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2002-01-30  Marcus Brinkmann  <marcus@g10code.de>
+
+	* gpgme.texi: Add all the gpgme_op_*_start functions.
+	Fill the concept index with many, many entries.
+
 2002-01-29  Marcus Brinkmann  <marcus@g10code.de>
 
 	* gpgme.texi (Run Control): New section.
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index c1327dd..cdefc50 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -149,8 +149,8 @@ Key Management
 * Manipulating Keys::             Operations on keys.
 * Generating Keys::               Creating new key pairs.
 * Exporting Keys::                Retrieving key data from the key ring.
-* Importing Keys::                Adding keys to the keyring.
-* Deleting Keys::                 Removing keys from the keyring.
+* Importing Keys::                Adding keys to the key ring.
+* Deleting Keys::                 Removing keys from the key ring.
 
 Trust Item Management
 
@@ -165,7 +165,7 @@ Crypto Operations
 * Decrypt and Verify::            Decrypting a signed ciphertext.
 * Sign::                          Creating a signature.
 * Encrypt::                       Encrypting a plaintext.
-* More Information::              How to obtain more info about the operation.
+* Detailed Results::              How to obtain more info about the operation.
 
 Sign
 
@@ -213,7 +213,7 @@ This library documents the @acronym{GPGME} library programming
 interface.  All functions and data types provided by the library are
 explained.
 
-The reader is assumed to posess basic knowledge about cryptography in
+The reader is assumed to possess basic knowledge about cryptography in
 general, and public key cryptography in particular.  The underlying
 cryptographic engines that are used by the library are not explained,
 but where necessary, special features or requirements by an engine are
@@ -277,6 +277,8 @@ including listing keys, querying their attributes, generating,
 importing, exporting and deleting keys, and acquiring information
 about the trust path.
 
+@cindex thread-safeness
+@cindex multi-threading
 @strong{Caution:} The @acronym{GPGME} library is not thread-safe.  It
 will be to some extent in the future, but currently great care has to
 be taken if @acronym{GPGME} is used in a multi-threaded environment.
@@ -300,6 +302,8 @@ of the library are verified.
 
 @node Header
 @section Header
+@cindex header file
+@cindex include file
 
 All interfaces (data types and functions) of the library are defined
 in the header file `gpgme.h'.  You must include this in all programs
@@ -317,6 +321,8 @@ symbols.
 
 @node Building the Source
 @section Building the Source
+@cindex compiler options
+@cindex compiler flags
 
 If you want to compile a source file including the `gpgme.h' header
 file, you must make sure that the compiler can find it in the
@@ -364,6 +370,7 @@ gcc -o foo foo.c `gpgme-config --cflags --libs`
 
 @node Library Version Check
 @section Library Version Check
+@cindex version check, of the library
 
 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
 The function @code{gpgme_check_version} has three purposes.  It can be
@@ -396,6 +403,11 @@ features are provided by the installed version of the library.
 
 @node Protocols and Engines
 @chapter Protocols and Engines
+@cindex protocol
+@cindex engine
+@cindex crypto engine
+@cindex backend
+@cindex crypto backend
 
 @acronym{GPGME} supports several cryptographic protocols, however, it
 does not implement them.  Rather it uses backends (also called
@@ -409,6 +421,7 @@ necessary, @acronym{GPGME} provides the necessary callback function
 hooks and further interfaces.
 
 @deftp {Data type} {enum GpgmeProtocol}
+@tindex GpgmeProtocol
 The @code{GpgmeProtocol} type specifies the set of possible protocol
 values that are supported by @acronym{GPGME}.  The following protocols
 are supported:
@@ -431,6 +444,7 @@ This specifies the Cryptographic Message Syntax.
 
 @node Engine Version Check
 @section Engine Version Check
+@cindex version check, of the engines
 
 @deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
 The function @code{gpgme_engine_check_version} verifies that the
@@ -455,6 +469,7 @@ only.  It is obsoleted by @code{gpgme_engine_check_version}.
 
 @node Engine Information
 @section Engine Information
+@cindex engine, information about
 
 @deftypefun {const char *} gpgme_get_engine_info (void)
 The function @code{gpgme_get_engine_info} returns an @acronym{XML}
@@ -496,6 +511,10 @@ return on your system:
 
 @node OpenPGP
 @section OpenPGP
+@cindex OpenPGP
+@cindex GnuPG
+@cindex protocol, GnuPG
+@cindex engine, GnuPG
 
 OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
 This is the first protocol that was supported by @acronym{GPGME}.
@@ -505,6 +524,13 @@ The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
 
 @node Cryptographic Message Syntax
 @section Cryptographic Message Syntax
+@cindex CMS
+@cindex cryptographic message syntax
+@cindex GpgSM
+@cindex protocol, CMS
+@cindex engine, GpgSM
+@cindex S/MIME
+@cindex protocol, S/MIME
 
 @acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
 GnuPG.
@@ -514,6 +540,7 @@ The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
 
 @node Error Handling
 @chapter Error Handling
+@cindex error handling
 
 Many functions in @acronym{GPGME} can return an error if they fail.
 For this reason, the application should always catch the error
@@ -538,8 +565,10 @@ described in the documentation of those functions.
 
 @node Error Values
 @section Error Values
+@cindex error values, list of
 
 @deftp {Data type} {enum GpgmeError}
+@tindex GpgmeError
 The @code{GpgmeError} type specifies the set of all error values that
 are used by @acronym{GPGME}.  Possible values are:
 
@@ -644,6 +673,8 @@ engine is not installed properly.
 
 @node Error Strings
 @section Error Strings
+@cindex error values, printing of
+@cindex error strings
 
 @deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}})
 The function @code{gpgme_strerror} returns a pointer to a statically
@@ -655,6 +686,7 @@ message to the user.
 
 @node Exchanging Data
 @chapter Exchanging Data
+@cindex data, exchanging
 
 A lot of data has to be exchanged between the user and the crypto
 engine, like plaintext messages, ciphertext, signatures and
@@ -678,6 +710,7 @@ data, which is used by @acronym{GPGME} to exchange data with the user.
 
 @node Creating Data Buffers
 @section Creating Data Buffers
+@cindex data buffer, creation
 
 @deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
 The function @code{gpgme_data_new} creates a new @code{GpgmeData}
@@ -768,6 +801,7 @@ not enough memory is available.
 
 @node Destroying Data Buffers
 @section Destroying Data Buffers
+@cindex data buffer, destruction
 
 @deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
 The function @code{gpgme_data_release} destroys the data object with
@@ -791,6 +825,7 @@ be returned to the user, the function will return @code{NULL}.
 
 @node Manipulating Data Buffers
 @section Manipulating Data Buffers
+@cindex data buffere, manipulation
 
 @deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{nread}})
 The function @code{gpgme_data_read} reads up to @var{length} bytes
@@ -836,6 +871,7 @@ available.
 @end deftypefun
 
 @deftp {Data type} {enum GpgmeDataType}
+@tindex GpgmeDataType
 The @code{GpgmeDataType} type specifies the type of a @code{GpgmeData} object.
 The following data types are available:
 
@@ -867,6 +903,7 @@ object with the handle @var{dh}.  If @var{dh} is not a valid pointer,
 
 @node Contexts
 @chapter Contexts
+@cindex context
 
 All cryptograhic operations in @acronym{GPGME} are performed within a
 context, which contains the internal state of the operation as well as
@@ -893,6 +930,7 @@ cryptographic operations.
 
 @node Creating Contexts
 @section Creating Contexts
+@cindex context, creation
 
 @deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
 The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
@@ -905,9 +943,9 @@ available.
 @end deftypefun
 
 
-
 @node Destroying Contexts
 @section Destroying Contexts
+@cindex context, destruction
 
 @deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
 The function @code{gpgme_release} destroys the context with the handle
@@ -917,6 +955,7 @@ The function @code{gpgme_release} destroys the context with the handle
 
 @node Context Attributes
 @section Context Attributes
+@cindex context, attributes
 
 @menu
 * Protocol Selection::            Selecting the protocol used by a context.
@@ -930,6 +969,8 @@ The function @code{gpgme_release} destroys the context with the handle
 
 @node Protocol Selection
 @subsection Protocol Selection
+@cindex context, selecting protocol
+@cindex protocol, selecting
 
 @deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}})
 The function @code{gpgme_set_protocol} sets the protocol used within
@@ -949,6 +990,9 @@ not a valid protocol.
 
 @node @acronym{ASCII} Armor
 @subsection @acronym{ASCII} Armor
+@cindex context, armor mode
+@cindex @acronym{ASCII} armor
+@cindex armor mode
 
 @deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
 The function @code{gpgme_set_armor} specifies if the output should be
@@ -968,6 +1012,9 @@ not a valid pointer.
 
 @node Text Mode
 @subsection Text Mode
+@cindex context, text mode
+@cindex text mode
+@cindex canonical text mode
 
 @deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
 The function @code{gpgme_set_textmode} specifies if canonical text mode
@@ -990,6 +1037,8 @@ valid pointer.
 
 @node Key Listing Mode
 @subsection Key Listing Mode
+@cindex key listing mode
+@cindex key listing, mode of
 
 @deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
 The function @code{gpgme_set_keylist_mode} changes the default
@@ -1007,8 +1056,11 @@ Fast listing without information about the key validity.
 
 @node Passphrase Callback
 @subsection Passphrase Callback
+@cindex callback, passphrase
+@cindex passphrase callback
 
 @deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})}
+@tindex GpgmePassphraseCb
 The @code{GpgmePasshraseCb} type is the type of functions usable as
 passphrase callback function.
 
@@ -1044,8 +1096,11 @@ calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
 
 @node Progress Meter Callback
 @subsection Progress Meter Callback
+@cindex callback, progress meter
+@cindex progress meter callback
 
 @deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
+@tindex GpgmeProgressCb
 The @code{GpgmeProgressCb} type is the type of functions usable as
 progress callback function.
 
@@ -1074,6 +1129,7 @@ calling @code{gpgme_set_progress_cb} with @var{progfunc} being
 
 @node Key Management
 @section Key Management
+@cindex key management
 
 Some of the cryptographic operations require that recipients or
 signers are specified.  This is always done by specifying the
@@ -1093,13 +1149,18 @@ A key can contain several user IDs and sub keys.
 * Manipulating Keys::             Operations on keys.
 * Generating Keys::               Creating new key pairs.
 * Exporting Keys::                Retrieving key data from the key ring.
-* Importing Keys::                Adding keys to the keyring.
-* Deleting Keys::                 Removing keys from the keyring.
+* Importing Keys::                Adding keys to the key ring.
+* Deleting Keys::                 Removing keys from the key ring.
 @end menu
 
 
 @node Listing Keys
 @subsection Listing Keys
+@cindex listing keys
+@cindex key listing
+@cindex key listing, start
+@cindex key ring, list
+@cindex key ring, search
 
 @deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
 The function @code{gpgme_op_keylist_start} initiates a key listing
@@ -1154,6 +1215,9 @@ operation there was not enough memory available.
 
 @node Information About Keys
 @subsection Information About Keys
+@cindex key, information about
+@cindex key, attributes
+@cindex attributes, of a key
 
 @deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
 The function @code{gpgme_key_get_as_xml} returns a string in
@@ -1344,6 +1408,7 @@ or @var{reserved} not @code{NULL}.
 
 @node Manipulating Keys
 @subsection Manipulating Keys
+@cindex key, manipulation
 
 @deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
 The function @code{gpgme_key_ref} acquires an additional reference for
@@ -1363,10 +1428,12 @@ The function @code{gpgme_key_release} is an alias for
 
 @node Generating Keys
 @subsection Generating Keys
+@cindex key, creation
+@cindex key ring, add
 
 @deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
 The function @code{gpgme_op_genkey} generates a new key pair in the
-context @var{ctx} and puts it into the standard keyring if both
+context @var{ctx} and puts it into the standard key ring if both
 @var{pubkey} and @var{seckey} are @code{NULL}.  In this case the
 function returns immediately after starting the operation, and does
 not wait for it to complete.  @var{pubkey} and @var{seckey} are
@@ -1377,7 +1444,7 @@ implemented yet).
 
 The argument @var{parms} specifies parameters for the key in an XML
 string.  The details about the format of @var{parms} are specific to
-teh crypto engine used by @var{ctx}.  Here is an example for GnuPG as
+the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
 the crypto engine:
 
 @example
@@ -1404,14 +1471,27 @@ container is passed verbatim to GnuPG.  Control statements are not
 allowed.
 
 The function returns @code{GPGME_No_Error} if the operation could be
-started, @code{GPGME_Invalid_Value} if @var{parms} is not a valid XML
-string, and @code{GPGME_Not_Supported} if @var{pubkey} or @var{seckey}
-is not @code{NULL}.
+started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
+a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
+@var{seckey} is not @code{NULL}.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
+The function @code{gpgme_op_genkey_start} initiates a
+@code{gpgme_op_genkey} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{GPGME_No_Error} if the operation could be
+started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
+a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
+@var{seckey} is not @code{NULL}.
 @end deftypefun
 
 
 @node Exporting Keys
 @subsection Exporting Keys
+@cindex key, export
+@cindex key ring, export from
 
 @deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
 The function @code{gpgme_op_export} extracts the public keys of the
@@ -1426,9 +1506,22 @@ passes through any errors that are reported by the crypto engine
 support routines.
 @end deftypefun
 
+@deftypefun GpgmeError gpgme_op_export_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
+The function @code{gpgme_op_export_start} initiates a
+@code{gpgme_op_export} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{GPGME_No_Error} if the operation could be
+started successfully, and @code{GPGME_Invalid_Value} if
+@var{recipients} is @code{NULL} or @var{keydata} is not a valid empty
+data buffer.
+@end deftypefun
+
 
 @node Importing Keys
 @subsection Importing Keys
+@cindex key, import
+@cindex key ring, import to
 
 @deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
 The function @code{gpgme_op_import} adds the keys in the data buffer
@@ -1442,9 +1535,22 @@ or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
 @var{keydata} is an empty data buffer.
 @end deftypefun
 
+@deftypefun GpgmeError gpgme_op_import_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
+The function @code{gpgme_op_import_start} initiates a
+@code{gpgme_op_import} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{GPGME_No_Error} if the import could be
+started successfully, @code{GPGME_Invalid_Value} if @var{keydata} if
+@var{ctx} or @var{keydata} is not a valid pointer, and
+@code{GPGME_No_Data} if @var{keydata} is an empty data buffer.
+@end deftypefun
+
 
 @node Deleting Keys
 @subsection Deleting Keys
+@cindex key, delete
+@cindex key ring, delete from
 
 @deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
 The function @code{gpgme_op_delete} deletes the key @var{key} from the
@@ -1457,9 +1563,20 @@ successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or @var{key}
 is not a valid pointer.
 @end deftypefun
 
+@deftypefun GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
+The function @code{gpgme_op_delete_start} initiates a
+@code{gpgme_op_delete} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{GPGME_No_Error} if the operation was
+started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or
+@var{key} is not a valid pointer.
+@end deftypefun
+
 
 @node Trust Item Management
 @section Trust Item Management
+@cindex trust item
 
 @strong{Caution:} The trust items interface is experimental.
 
@@ -1476,6 +1593,7 @@ The @code{GpgmeTrustItem} type is a handle for a trust item.
 
 @node Listing Trust Items
 @subsection Listing Trust Items
+@cindex trust item list
 
 @deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
 The function @code{gpgme_op_trustlist_start} initiates a trust item
@@ -1529,6 +1647,9 @@ operation there was not enough memory available.
 
 @node Information About Trust Items
 @subsection Information About Trust Items
+@cindex trust item, information about
+@cindex trust item, attributes
+@cindex attributes, of a trust item
 
 Trust items have attributes which can be queried using the interfaces
 below.  The attribute identifiers are shared with those for key
@@ -1565,6 +1686,7 @@ or @var{reserved} not @code{NULL}.
 
 @node Manipulating Trust Items
 @subsection Manipulating Trust Items
+@cindex trust item, manipulation
 
 @deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
 The function @code{gpgme_trust_item_release} destroys a
@@ -1573,6 +1695,7 @@ The function @code{gpgme_trust_item_release} destroys a
 
 @node Crypto Operations
 @section Crypto Operations
+@cindex cryptographic operation
 
 @menu
 * Decrypt::                       Decrypting a ciphertext.
@@ -1580,12 +1703,14 @@ The function @code{gpgme_trust_item_release} destroys a
 * Decrypt and Verify::            Decrypting a signed ciphertext.
 * Sign::                          Creating a signature.
 * Encrypt::                       Encrypting a plaintext.
-* More Information::              How to obtain more info about the operation.
+* Detailed Results::              How to obtain more info about the operation.
 @end menu
 
 
 @node Decrypt
 @subsection Decrypt
+@cindex decryption
+@cindex cryptographic operation, decryption
 
 @deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
@@ -1602,22 +1727,27 @@ secret key could not be retrieved, and passes through any errors that
 are reported by the crypto engine support routines.
 @end deftypefun
 
-@c @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
-@c The function @code{gpgme_op_decrypt_start} initiates a
-@c @code{gpgme_op_decrypt} operation.  It can be completed by calling
-@c @code{gpgme_wait} on the context.
+@deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
+The function @code{gpgme_op_decrypt_start} initiates a
+@code{gpgme_op_decrypt} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
-@c The function returns @code{GPGME_No_Error} if the operation could be
-@c started, @code{GPGME_Invalid_Value} if @var{cipher} or @var{plain} is
-@c not a valid pointer, and passes through any errors that are reported
-@c by the crypto engine support routines.
-@c @end deftypefun
+The function returns @code{GPGME_No_Error} if the operation could be
+started successfully, and @code{GPGME_Invalid_Value} if @var{cipher}
+or @var{plain} is not a valid pointer.
+@end deftypefun
 
 
 @node Verify
 @subsection Verify
+@cindex verification
+@cindex signature, verification
+@cindex cryptographic operation, verification
+@cindex cryptographic operation, signature check
+@cindex signature, status
 
 @deftp {Data type} {enum GpgmeSigStat}
+@tindex GpgmeSigStat
 The @code{GpgmeSigStat} type holds the result of a signature check, or
 the combined result of all signatures.  The following results are
 possible:
@@ -1671,7 +1801,17 @@ data to verify, and passes through any errors that are reported by the
 crypto engine support routines.
 @end deftypefun
 
-@c GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig, GpgmeData plain);
+@deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}})
+The function @code{gpgme_op_verify_start} initiates a
+@code{gpgme_op_verify} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{GPGME_No_Error} if the operation could be
+started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
+@var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, and
+@code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
+data to verify.
+@end deftypefun
 
 @deftypefun {const char *} gpgme_get_sig_status (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigStat *@var{r_stat}}, @w{time_t *@var{r_created}})
 The function @code{gpgme_get_sig_status} receives information about a
@@ -1727,6 +1867,10 @@ The function returns a string if the notation data is available or
 
 @node Decrypt and Verify
 @subsection Decrypt and Verify
+@cindex decryption and verification
+@cindex verification and decryption
+@cindex signature check
+@cindex cryptographic operation, decryption and verification
 
 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
@@ -1748,11 +1892,25 @@ secret key could not be retrieved, and passes through any errors that
 are reported by the crypto engine support routines.
 @end deftypefun
 
-@c GpgmeError gpgme_op_decrypt_verify (GpgmeCtx c, GpgmeData in, GpgmeData out, GpgmeSigStat *r_status);
+@deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
+The function @code{gpgme_op_decrypt_verify_start} initiates a
+@code{gpgme_op_decrypt_verify} operation.  It can be completed by
+calling @code{gpgme_wait} on the context.  @xref{Waiting For
+Completion}.
+
+The function returns @code{GPGME_No_Error} if the operation could be
+started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
+@var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, and
+@code{GPGME_No_Data} if @var{cipher} does not contain any data to
+decrypt.
+@end deftypefun
 
 
 @node Sign
 @subsection Sign
+@cindex signature, creation
+@cindex sign
+@cindex cryptographic operation, signing
 
 A signature can contain signatures by one or more keys.  The set of
 keys used to create a signatures is contained in a context, and is
@@ -1767,6 +1925,8 @@ set is changed).
 
 @node Selecting Signers
 @subsubsection Selecting Signers
+@cindex signature, selecting signers
+@cindex signers, selecting
 
 @deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
 The function @code{gpgme_signers_clear} releases a reference for each
@@ -1776,7 +1936,6 @@ context @var{ctx}.
 Every context starts with an empty list.
 @end deftypefun
 
-
 @deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
 The function @code{gpgme_signers_add} adds the key @var{key} to the
 list of signers in the context @var{ctx}.
@@ -1797,6 +1956,7 @@ If @var{seq} is out of range, @code{NULL} is returned.
 @subsubsection Creating a Signature
 
 @deftp {Data type} {enum GpgmeSigMode}
+@tindex GpgmeSigMode
 The @code{GpgmeSigMode} type is used to specify the desired type of a
 signature.  The following modes are available:
 
@@ -1822,7 +1982,7 @@ the data object @var{plain} and returns it in the data object
 @var{ctx} and the requested signature mode @var{mode}.
 
 More information about the signatures is available with
-@code{gpgme_get_op_info}.  @xref{More Information}.
+@code{gpgme_get_op_info}.  @xref{Detailed Results}.
 
 The function returns @code{GPGME_No_Error} if the signature could be
 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@@ -1833,9 +1993,21 @@ through any errors that are reported by the crypto engine support
 routines.
 @end deftypefun
 
+@deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
+The function @code{gpgme_op_sign_start} initiates a
+@code{gpgme_op_sign} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{GPGME_No_Error} if the operation could be
+started successfully, and @code{GPGME_Invalid_Value} if @var{ctx},
+@var{plain} or @var{sig} is not a valid pointer.
+@end deftypefun
+
 
 @node Encrypt
 @subsection Encrypt
+@cindex encryption
+@cindex cryptographic operation, encryption
 
 One plaintext can be encrypted for several recipients at the same
 time.  The list of recipients is created independently of any context,
@@ -1849,6 +2021,8 @@ and then passed to the encryption operation.
 
 @node Selecting Recipients
 @subsubsection Selecting Recipients
+@cindex encryption, selecting recipients
+@cindex recipients
 
 @deftp {Data type} GpgmeRecipients
 The @code{GpgmeRecipients} type is a handle for a set of recipients
@@ -1937,7 +2111,7 @@ ciphertext created is determined by the @acronym{ASCII} armor and text
 mode attributes set for the context @var{ctx}.
 
 More information about the encrypted text is available with
-@code{gpgme_get_op_info}.  @xref{More Information}.
+@code{gpgme_get_op_info}.  @xref{Detailed Results}.
 
 The function returns @code{GPGME_No_Error} if the ciphertext could be
 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@@ -1948,11 +2122,24 @@ secret key could not be retrieved, and passes through any errors that
 are reported by the crypto engine support routines.
 @end deftypefun
 
+@deftypefun GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
+The function @code{gpgme_op_encrypt_start} initiates a
+@code{gpgme_op_encrypt} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{GPGME_No_Error} if the operation could be
+started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
+@var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
+@code{GPGME_No_Recipient} if @var{rset} does not contain any valid
+recipients.
+@end deftypefun
+
 
-@node More Information
-@subsection More Information
+@node Detailed Results
+@subsection Detailed Results
+@cindex cryptographic operation, detailed results
 
-@deftypefun char *gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
+@deftypefun {char *} gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
 The function @code{gpgme_get_op_info} retrieves more informaton about
 the last crypto operation.
 
@@ -1988,6 +2175,8 @@ available.
 
 @node Run Control
 @section Run Control
+@cindex run control
+@cindex cryptographic operation, running
 
 Some basic support for running operations asynchronously is available
 in @acronym{GPGME}.  You can use it to set up a context completely up
@@ -2003,6 +2192,8 @@ later point.
 
 @node Waiting For Completion
 @subsection Waiting For Completion
+@cindex cryptographic operation, wait for
+@cindex wait for completion
 
 @deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{int @var{hang}})
 The function @code{gpgme_wait} does continue the pending operation
@@ -2020,6 +2211,8 @@ The function returns @var{ctx}.
 
 @node Cancelling an Operation
 @subsection Cancelling an Operation
+@cindex cancellation
+@cindex cryptographic operation, cancel
 
 @deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}})
 The function @code{gpgme_cancel} tries to cancel the pending
@@ -2032,8 +2225,11 @@ asking for a passphrase again in the passphrase callback.
 
 @node Hooking Up Into Idle Time
 @subsection Hooking Up Into Idle Time
+@cindex idle time
+@cindex idle function
 
-@deftp {Data type} {void (*GpgmeIdleFnc) (void)}
+@deftp {Data type} {void (*GpgmeIdleFunc) (void)}
+@tindex GpgmeIdleFunc
 The @code{GpgmeIdleFunc} type is the type of functions usable as
 an idle function that can be registered with @code{gpgme_register_idle}.
 @end deftp
diff --git a/gpgme/ChangeLog b/gpgme/ChangeLog
index 1e92a83..2c0851f 100644
--- a/gpgme/ChangeLog
+++ b/gpgme/ChangeLog
@@ -1,3 +1,8 @@
+2002-01-30  Marcus Brinkmann  <marcus@g10code.de>
+
+	* gpgme.h: Add lots of comment and fix the formatting.  Add
+	gpgme_trustlist_end prototype.
+
 2002-01-29  Marcus Brinkmann  <marcus@g10code.de>
 
 	* gpgme.h: Add new type GpgmeIdleFunc.  Change type of
diff --git a/gpgme/gpgme.h b/gpgme/gpgme.h
index d729ec7..8823a7b 100644
--- a/gpgme/gpgme.h
+++ b/gpgme/gpgme.h
@@ -22,7 +22,7 @@
 #ifndef GPGME_H
 #define GPGME_H
 
-#include <stdio.h> /* for FILE * */
+#include <stdio.h> /* For FILE *.  */
 #ifdef _MSC_VER
   typedef long off_t;
 #else
@@ -37,287 +37,492 @@ extern "C" {
 #endif
 
 
-/*
- * The version of this header should match the one of the library
- * It should not be used by a program because gpgme_check_version(NULL)
- * does return the same version.  The purpose of this macro is to
- * let autoconf (using the AM_PATH_GPGME macro) check that this
- * header matches the installed library.
- * Warning: Do not edit the next line.  configure will do that for you! */
+/* 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.  Warning: Do not edit the next line.  configure will do
+   that for you!  */
 #define GPGME_VERSION "0.3.0a-cvs"
 
 
+/* The opaque data types used by GPGME.  */
 
+/* The context holds some global state and configration options as
+   well as the results of a crypto operation.  */
 struct gpgme_context_s;
 typedef struct gpgme_context_s *GpgmeCtx;
 
+/* The data object used by GPGME to exchange arbitrary data.  */
 struct gpgme_data_s;
 typedef struct gpgme_data_s *GpgmeData;
 
+/* A list of recipients to be used in an encryption operation.  */
 struct gpgme_recipients_s;
 typedef struct gpgme_recipients_s *GpgmeRecipients;
 
+/* A key from the keyring.  */
 struct gpgme_key_s;
 typedef struct gpgme_key_s *GpgmeKey;
 
+/* A trust item.  */
 struct gpgme_trust_item_s;
 typedef struct gpgme_trust_item_s *GpgmeTrustItem;
 
 
-typedef enum {
-    GPGME_EOF = -1,
-    GPGME_No_Error = 0,
-    GPGME_General_Error = 1,
-    GPGME_Out_Of_Core = 2,
-    GPGME_Invalid_Value = 3,
-    GPGME_Busy = 4,
-    GPGME_No_Request = 5,
-    GPGME_Exec_Error = 6,
-    GPGME_Too_Many_Procs = 7,
-    GPGME_Pipe_Error = 8,
-    GPGME_No_Recipients = 9,
-    GPGME_No_Data = 10,
-    GPGME_Conflict = 11,
-    GPGME_Not_Implemented = 12,
-    GPGME_Read_Error = 13,
-    GPGME_Write_Error = 14,
-    GPGME_Invalid_Type = 15,
-    GPGME_Invalid_Mode = 16,
-    GPGME_File_Error = 17,  /* errno is set in this case */
+/* The error numbers used by GPGME.  */
+typedef enum
+  {
+    GPGME_EOF               = -1,
+    GPGME_No_Error          = 0,
+    GPGME_General_Error     = 1,
+    GPGME_Out_Of_Core       = 2,
+    GPGME_Invalid_Value     = 3,
+    GPGME_Busy              = 4,
+    GPGME_No_Request        = 5,
+    GPGME_Exec_Error        = 6,
+    GPGME_Too_Many_Procs    = 7,
+    GPGME_Pipe_Error        = 8,
+    GPGME_No_Recipients     = 9,
+    GPGME_No_Data           = 10,
+    GPGME_Conflict          = 11,
+    GPGME_Not_Implemented   = 12,
+    GPGME_Read_Error        = 13,
+    GPGME_Write_Error       = 14,
+    GPGME_Invalid_Type      = 15,
+    GPGME_Invalid_Mode      = 16,
+    GPGME_File_Error        = 17,  /* errno is set in this case.  */
     GPGME_Decryption_Failed = 18,
-    GPGME_No_Passphrase = 19,
-    GPGME_Canceled = 20,
-    GPGME_Invalid_Key = 21,
-    GPGME_Invalid_Engine = 22
-} GpgmeError;
-
-typedef enum {
+    GPGME_No_Passphrase     = 19,
+    GPGME_Canceled          = 20,
+    GPGME_Invalid_Key       = 21,
+    GPGME_Invalid_Engine    = 22
+  }
+GpgmeError;
+
+/* The possible types of GpgmeData objects.  */
+typedef enum
+  {
     GPGME_DATA_TYPE_NONE = 0,
     GPGME_DATA_TYPE_MEM  = 1,
     GPGME_DATA_TYPE_FD   = 2,
     GPGME_DATA_TYPE_FILE = 3,
     GPGME_DATA_TYPE_CB   = 4
-} GpgmeDataType;
-
-typedef enum {
-    GPGME_SIG_STAT_NONE = 0,
-    GPGME_SIG_STAT_GOOD = 1,
-    GPGME_SIG_STAT_BAD  = 2,
+  }
+GpgmeDataType;
+
+/* The possible signature stati.  */
+typedef enum
+  {
+    GPGME_SIG_STAT_NONE  = 0,
+    GPGME_SIG_STAT_GOOD  = 1,
+    GPGME_SIG_STAT_BAD   = 2,
     GPGME_SIG_STAT_NOKEY = 3,
     GPGME_SIG_STAT_NOSIG = 4,
     GPGME_SIG_STAT_ERROR = 5,
     GPGME_SIG_STAT_DIFF  = 6
-} GpgmeSigStat;
+  }
+GpgmeSigStat;
 
-typedef enum {
+/* The available signature modes.  */
+typedef enum
+  {
     GPGME_SIG_MODE_NORMAL = 0,
     GPGME_SIG_MODE_DETACH = 1,
-    GPGME_SIG_MODE_CLEAR = 2
-} GpgmeSigMode;
-
-typedef enum {
-    GPGME_ATTR_KEYID   = 1,
-    GPGME_ATTR_FPR     = 2,
-    GPGME_ATTR_ALGO    = 3,
-    GPGME_ATTR_LEN     = 4,
-    GPGME_ATTR_CREATED = 5,
-    GPGME_ATTR_EXPIRE  = 6,
-    GPGME_ATTR_OTRUST  = 7,
-    GPGME_ATTR_USERID  = 8,
-    GPGME_ATTR_NAME    = 9,
-    GPGME_ATTR_EMAIL   = 10,
-    GPGME_ATTR_COMMENT = 11,
-    GPGME_ATTR_VALIDITY= 12,
-    GPGME_ATTR_LEVEL   = 13,
-    GPGME_ATTR_TYPE    = 14,
-    GPGME_ATTR_IS_SECRET= 15,
-    GPGME_ATTR_KEY_REVOKED = 16,
-    GPGME_ATTR_KEY_INVALID = 17,
-    GPGME_ATTR_UID_REVOKED = 18,
-    GPGME_ATTR_UID_INVALID = 19,
-    GPGME_ATTR_KEY_CAPS    = 20,
-    GPGME_ATTR_CAN_ENCRYPT = 21,
-    GPGME_ATTR_CAN_SIGN    = 22,
-    GPGME_ATTR_CAN_CERTIFY = 23,
-    GPGME_ATTR_KEY_EXPIRED = 24,
-    GPGME_ATTR_KEY_DISABLED= 25
-} GpgmeAttr;
-
-typedef enum {
-    GPGME_VALIDITY_UNKNOWN = 0,
+    GPGME_SIG_MODE_CLEAR  = 2
+  }
+GpgmeSigMode;
+
+/* The available key attributes.  */
+typedef enum
+  {
+    GPGME_ATTR_KEYID        = 1,
+    GPGME_ATTR_FPR          = 2,
+    GPGME_ATTR_ALGO         = 3,
+    GPGME_ATTR_LEN          = 4,
+    GPGME_ATTR_CREATED      = 5,
+    GPGME_ATTR_EXPIRE       = 6,
+    GPGME_ATTR_OTRUST       = 7,
+    GPGME_ATTR_USERID       = 8,
+    GPGME_ATTR_NAME         = 9,
+    GPGME_ATTR_EMAIL        = 10,
+    GPGME_ATTR_COMMENT      = 11,
+    GPGME_ATTR_VALIDITY     = 12,
+    GPGME_ATTR_LEVEL        = 13,
+    GPGME_ATTR_TYPE         = 14,
+    GPGME_ATTR_IS_SECRET    = 15,
+    GPGME_ATTR_KEY_REVOKED  = 16,
+    GPGME_ATTR_KEY_INVALID  = 17,
+    GPGME_ATTR_UID_REVOKED  = 18,
+    GPGME_ATTR_UID_INVALID  = 19,
+    GPGME_ATTR_KEY_CAPS     = 20,
+    GPGME_ATTR_CAN_ENCRYPT  = 21,
+    GPGME_ATTR_CAN_SIGN     = 22,
+    GPGME_ATTR_CAN_CERTIFY  = 23,
+    GPGME_ATTR_KEY_EXPIRED  = 24,
+    GPGME_ATTR_KEY_DISABLED = 25
+  }
+GpgmeAttr;
+
+/* The available validities for a trust item or key.  */
+typedef enum
+  {
+    GPGME_VALIDITY_UNKNOWN   = 0,
     GPGME_VALIDITY_UNDEFINED = 1,
-    GPGME_VALIDITY_NEVER = 2,
-    GPGME_VALIDITY_MARGINAL = 3,
-    GPGME_VALIDITY_FULL = 4,
-    GPGME_VALIDITY_ULTIMATE = 5
-} GpgmeValidity;
-
-
-typedef enum {
-  GPGME_PROTOCOL_OpenPGP = 0, /* default */
-  GPGME_PROTOCOL_CMS = 1,
-  GPGME_PROTOCOL_AUTO = 2
-} GpgmeProtocol;
-
-typedef const char *(*GpgmePassphraseCb)(void*,
-                                         const char *desc, void **r_hd);
-typedef void (*GpgmeProgressCb)(void *opaque,
-                                const char *what, 
-                                int type, int current, int total );
-
-/* Context management */
-GpgmeError gpgme_new (GpgmeCtx *r_ctx);
-void       gpgme_release (GpgmeCtx c);
-void       gpgme_cancel (GpgmeCtx c);
-GpgmeCtx   gpgme_wait (GpgmeCtx c, int hang);
-
-char *gpgme_get_notation (GpgmeCtx c);
-GpgmeError gpgme_set_protocol (GpgmeCtx c, GpgmeProtocol prot);
-void gpgme_set_armor (GpgmeCtx c, int yes);
-int  gpgme_get_armor (GpgmeCtx c);
-void gpgme_set_textmode (GpgmeCtx c, int yes);
-int  gpgme_get_textmode (GpgmeCtx c);
-void gpgme_set_keylist_mode ( GpgmeCtx c, int mode );
-void gpgme_set_passphrase_cb (GpgmeCtx c,
-                              GpgmePassphraseCb cb, void *cb_value);
-void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *cb_value);
-
-void       gpgme_signers_clear (GpgmeCtx c);
-GpgmeError gpgme_signers_add (GpgmeCtx c, const GpgmeKey key);
-GpgmeKey   gpgme_signers_enum (const GpgmeCtx c, int seq);
-
-const char *gpgme_get_sig_status (GpgmeCtx c, int idx,
-                                  GpgmeSigStat *r_stat, time_t *r_created );
-GpgmeError gpgme_get_sig_key (GpgmeCtx c, int idx, GpgmeKey *r_key);
-char *gpgme_get_op_info (GpgmeCtx c, int reserved);
-
-
-/* Functions to handle recipients */
-GpgmeError   gpgme_recipients_new (GpgmeRecipients *r_rset);
-void         gpgme_recipients_release ( GpgmeRecipients rset);
-GpgmeError   gpgme_recipients_add_name (GpgmeRecipients rset,
-                                        const char *name);
-GpgmeError   gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
-                                                      const char *name,
-                                                      GpgmeValidity val );
-unsigned int gpgme_recipients_count ( const GpgmeRecipients rset );
-GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,void **ctx);
-const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,void **ctx);
-GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,void **ctx);
-
-
-/* Functions to handle data sources */
-GpgmeError    gpgme_data_new ( GpgmeData *r_dh );
-GpgmeError    gpgme_data_new_from_mem ( GpgmeData *r_dh,
-                                        const char *buffer, size_t size,
-                                        int copy );
-GpgmeError    gpgme_data_new_with_read_cb ( GpgmeData *r_dh,
-                              int (*read_cb)(void*,char *,size_t,size_t*),
-                              void *read_cb_value );
-
-GpgmeError    gpgme_data_new_from_file ( GpgmeData *r_dh,
-                                         const char *fname,
-                                         int copy );
+    GPGME_VALIDITY_NEVER     = 2,
+    GPGME_VALIDITY_MARGINAL  = 3,
+    GPGME_VALIDITY_FULL      = 4,
+    GPGME_VALIDITY_ULTIMATE  = 5
+  }
+GpgmeValidity;
+
+/* The available protocols.  */
+typedef enum
+  {
+    GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
+    GPGME_PROTOCOL_CMS     = 1,
+    GPGME_PROTOCOL_AUTO    = 2
+  }
+GpgmeProtocol;
+
+
+/* Types for callback functions.  */
+
+/* Request a passphrase from the user.  */
+typedef const char *(*GpgmePassphraseCb) (void *hook, const char *desc,
+					  void **r_hd);
+
+/* Inform the user about progress made.  */
+typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
+				 int type, int current, int total);
+
+
+/* Context management functions.  */
+
+/* Create a new context and return it in CTX.  */
+GpgmeError gpgme_new (GpgmeCtx *ctx);
+
+/* Release the context CTX.  */
+void gpgme_release (GpgmeCtx ctx);
+
+/* Retrieve more info about performed signature check.  */
+char *gpgme_get_notation (GpgmeCtx ctx);
+
+/* Set the protocol to be used by CTX to PROTO.  */
+GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
+
+/* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
+void gpgme_set_armor (GpgmeCtx ctx, int yes);
+
+/* Return non-zero if armor mode is set in CTX.  */
+int gpgme_get_armor (GpgmeCtx ctx);
+
+/* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
+void gpgme_set_textmode (GpgmeCtx ctx, int yes);
+
+/* Return non-zero if text mode is set in CTX.  */
+int gpgme_get_textmode (GpgmeCtx ctx);
+
+/* Set keylist mode in CTX to MODE.  */
+void gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
+
+/* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
+   passed as first argument to the passphrase callback function.  */
+void gpgme_set_passphrase_cb (GpgmeCtx ctx,
+                              GpgmePassphraseCb 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.  */
+void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
+
+/* Delete all signers from CTX.  */
+void gpgme_signers_clear (GpgmeCtx ctx);
+
+/* Add KEY to list of signers in CTX.  */
+GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
+
+/* Return the SEQth signer's key in CTX.  */
+GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
+
+/* 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.  */
+const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
+                                  GpgmeSigStat *r_stat, time_t *r_created);
+
+/* Get the key used to create signature IDX in CTX and return it in
+   R_KEY.  */
+GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
+
+/* Return a string with more info about the last crypto operating in CTX.
+   RESERVED should be zero.  The user has to free the string.  */
+char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
+
+
+/* Run control.  */
+
+/* Cancel a pending operation in CTX.  */
+void       gpgme_cancel (GpgmeCtx ctx);
+
+/* Process the pending operation and, if HANG is non-zero, wait for
+   the pending operation to finish.  */
+GpgmeCtx gpgme_wait (GpgmeCtx ctx, int hang);
+
+
+/* Functions to handle recipients.  */
+
+/* Create a new recipients set and return it in R_RSET.  */
+GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
+
+/* Release the recipients set RSET.  */
+void gpgme_recipients_release (GpgmeRecipients rset);
+
+/* Add NAME to the recipients set RSET.  */
+GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
+
+/* Add NAME with validity AL to the recipients set RSET.  */
+GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
+                                                    const char *name,
+						    GpgmeValidity val);
+
+/* Return the number of recipients in RSET.  */
+unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
+
+/* Create a new enumeration handle for the recipients set RSET and
+   return it in ITER.  */
+GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
+				       void **iter);
+
+/* Return the next recipient from the recipient set RSET in the
+   enumerator ITER.  */
+const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
+					void **iter);
+
+/* Destroy the enumerator ITER for the recipient set RSET.  */
+GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
+					void **iter);
+
+
+/* Functions to handle data objects.  */
+
+/* Create a new data buffer and return it in R_DH.  */
+GpgmeError gpgme_data_new (GpgmeData *r_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.  */
+GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
+				    const char *buffer, size_t size,
+				    int copy);
+
+/* Create a new data buffer which retrieves the data from the callback
+   function READ_CB.  */
+GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
+					int (*read_cb) (void*,char *,size_t,size_t*),
+					void *read_cb_value);
+
+/* Create a new data buffer filled with the content of file FNAME.
+   COPY must be non-zero (delayed reads are not supported yet).  */
+GpgmeError gpgme_data_new_from_file (GpgmeData *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).  */
 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
 					 const char *fname, FILE *fp,
 					 off_t offset, size_t length);
-void          gpgme_data_release ( GpgmeData dh );
-char *        gpgme_data_release_and_get_mem ( GpgmeData dh, size_t *r_len );
-GpgmeDataType gpgme_data_get_type ( GpgmeData dh );
-GpgmeError    gpgme_data_rewind ( GpgmeData dh );
-GpgmeError    gpgme_data_read ( GpgmeData dh,
-                                char *buffer, size_t length, size_t *nread );
-GpgmeError    gpgme_data_write ( GpgmeData dh,
-                                 const char *buffer, size_t length );
 
+/* Destroy the data buffer DH.  */
+void gpgme_data_release (GpgmeData dh);
+
+/* Destroy the data buffer DH and return a pointer to its content.
+   The memory has be to released with free by the user.  It's size is
+   returned in R_LEN.  */
+char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
+
+/* Return the type of the data buffer DH.  */
+GpgmeDataType gpgme_data_get_type (GpgmeData dh);
+
+/* Reset the read pointer in DH.  */
+GpgmeError gpgme_data_rewind (GpgmeData dh);
+
+/* Read LENGTH bytes from the data object DH and store them in the
+   memory starting at BUFFER.  The number of bytes actually read is
+   returned in NREAD.  */
+GpgmeError gpgme_data_read (GpgmeData dh, char *buffer,
+			    size_t length, size_t *nread);
+
+/* Write LENGTH bytes starting from BUFFER into the data object DH.  */
+GpgmeError gpgme_data_write (GpgmeData dh, const char *buffer, size_t length);
+
+
+/* Key and trust functions.  */
 
-/* Key and trust functions */
+/* Acquire a reference to KEY.  */
 void gpgme_key_ref (GpgmeKey key);
-void gpgme_key_unref (GpgmeKey key);
-void gpgme_key_release ( GpgmeKey key );
-char *gpgme_key_get_as_xml ( GpgmeKey key );
-const char  *gpgme_key_get_string_attr ( GpgmeKey key, GpgmeAttr what,
-                                         const void *reserved, int idx );
-unsigned long gpgme_key_get_ulong_attr ( GpgmeKey key, GpgmeAttr what,
-                                         const void *reserved, int idx );
-
-void gpgme_trust_item_release ( GpgmeTrustItem item );
-const char *gpgme_trust_item_get_string_attr ( GpgmeTrustItem item,
-                                               GpgmeAttr what,
-                                               const void *reserved, int idx );
-int gpgme_trust_item_get_int_attr ( GpgmeTrustItem item, GpgmeAttr what,
-                                    const void *reserved, int idx );
-
-
-
-
-/* Basic GnuPG functions */
-GpgmeError gpgme_op_encrypt_start ( GpgmeCtx c,
-                                    GpgmeRecipients recp,
-                                    GpgmeData in, GpgmeData out );
-GpgmeError gpgme_op_decrypt_start ( GpgmeCtx c, 
-                                    GpgmeData ciph, GpgmeData plain );
-GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx c, 
-					  GpgmeData ciph, GpgmeData plain);
-GpgmeError gpgme_op_sign_start ( GpgmeCtx c,
-                                 GpgmeData in, GpgmeData out,
-                                 GpgmeSigMode mode );
-GpgmeError gpgme_op_verify_start ( GpgmeCtx c,
-                                   GpgmeData sig, GpgmeData text );
-GpgmeError gpgme_op_import_start ( GpgmeCtx c, GpgmeData keydata );
-GpgmeError gpgme_op_export_start ( GpgmeCtx c, GpgmeRecipients recp,
-                                   GpgmeData keydata );
-GpgmeError gpgme_op_genkey_start ( GpgmeCtx c, const char *parms,
-                                   GpgmeData pubkey, GpgmeData seckey );
-GpgmeError gpgme_op_delete_start ( GpgmeCtx c, const GpgmeKey key,
-                                   int allow_secret );
 
+/* Release a reference to KEY.  If this was the last one the key is
+   destroyed.  */
+void gpgme_key_unref (GpgmeKey key);
+void gpgme_key_release (GpgmeKey key);
+
+/* Get the data from key KEY in a XML string, which has to be released
+   with free by the user.  */
+char *gpgme_key_get_as_xml (GpgmeKey key);
+
+/* Return the value of the attribute WHAT of KEY, which has to be
+   representable by a string.  IDX specifies a running index if the
+   attribute appears more than once in the key.  */
+const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
+				       const void *reserved, int idx);
+
+/* Return the value of the attribute WHAT of KEY, which has to be
+   representable by an unsigned integer.  IDX specifies a running
+   index if the attribute appears more than once in the key.  */
+unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
+					const void *reserved, int idx);
+
+/* Release the trust item ITEM.  */
+void gpgme_trust_item_release (GpgmeTrustItem item);
+
+/* Return the value of the attribute WHAT of ITEM, which has to be
+   representable by a string.  IDX specifies a running index if the
+   attribute appears more than once in the key.  */
+const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
+					      GpgmeAttr what,
+					      const void *reserved, int idx);
+
+/* 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.  */
+int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
+				   const void *reserved, int idx);
+
+
+/* Crypto operation function.  */
+
+/* Encrypt plaintext PLAIN within CTX for the recipients RECP and
+   store the resulting ciphertext in CIPHER.  */
+GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
+				   GpgmeRecipients recp,
+				   GpgmeData plain, GpgmeData cipher);
+GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
+			     GpgmeRecipients recp,
+			     GpgmeData plain, GpgmeData cipher);
+
+/* Decrypt ciphertext CIPHER within CTX and store the resulting
+   plaintext in PLAIN.  */
+GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
+				   GpgmeData cipher, GpgmeData plain);
+GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
+			     GpgmeData cipher, GpgmeData plain);
+
+/* Decrypt ciphertext CIPHER and make a signature verification within
+   CTX and store the resulting plaintext in PLAIN.  */
+GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
+					  GpgmeData cipher, GpgmeData plain);
+GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
+				    GpgmeData cipher, GpgmeData plain,
+				    GpgmeSigStat *r_status);
 
+/* Sign the plaintext PLAIN and store the signature in SIG.  Only
+   detached signatures are supported for now.  */
+GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
+				GpgmeData plain, GpgmeData sig,
+				GpgmeSigMode mode);
+GpgmeError gpgme_op_sign (GpgmeCtx ctx,
+			  GpgmeData plain, GpgmeData sig,
+			  GpgmeSigMode mode);
+
+/* Verify within CTX that SIG is a valid signature for TEXT.  */
+GpgmeError gpgme_op_verify_start (GpgmeCtx ctx,
+				  GpgmeData sig, GpgmeData text);
+GpgmeError gpgme_op_verify (GpgmeCtx ctx,
+			    GpgmeData sig, GpgmeData text,
+			    GpgmeSigStat *r_status);
+
+/* Import the key in KEYDATA into the keyring.  */
+GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
+GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
+
+/* Export the keys listed in RECP into KEYDATA.  */
+GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
+				  GpgmeData keydata);
+GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
+			    GpgmeData keydata);
+
+/* 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.  */
+GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
+				  GpgmeData pubkey, GpgmeData seckey);
+GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
+			    GpgmeData pubkey, GpgmeData seckey);
+
+/* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
+   keys are also deleted.  */
+GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
+				  int allow_secret);
+GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
+			    int allow_secret);
 
 
 /* Key management functions */
+
+/* Start a keylist operation within CTX, searching for keys which
+   match PATTERN.  If SECRET_ONLY is true, only secret keys are
+   returned.  */
 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
 				   const char *pattern, int secret_only);
+
+/* Return the next key from the keylist in R_KEY.  */
 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
+
+/* Terminate a pending keylist operation within CTX.  */
 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
+
+
+/* Start a trustlist operation within CTX, searching for trust items
+   which match PATTERN.  */
 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
 				     const char *pattern, int max_level);
+
+/* Return the next trust item from the trustlist in R_ITEM.  */
 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
 
+/* Terminate a pending trustlist operation within CTX.  */
+GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
 
 
-/* Convenience functions for normal usage */
-GpgmeError gpgme_op_encrypt ( GpgmeCtx c, GpgmeRecipients recp,
-                              GpgmeData in, GpgmeData out );
-GpgmeError gpgme_op_decrypt ( GpgmeCtx c, 
-                              GpgmeData in, GpgmeData out );
-GpgmeError gpgme_op_decrypt_verify (GpgmeCtx c, 
-				    GpgmeData in, GpgmeData out,
-				    GpgmeSigStat *r_status);
-GpgmeError gpgme_op_sign ( GpgmeCtx c, GpgmeData in, GpgmeData out,
-                           GpgmeSigMode mode);
-GpgmeError gpgme_op_verify ( GpgmeCtx c, GpgmeData sig, GpgmeData text,
-                             GpgmeSigStat *r_status );
-GpgmeError gpgme_op_import ( GpgmeCtx c, GpgmeData keydata );
-GpgmeError gpgme_op_export ( GpgmeCtx c, GpgmeRecipients recp,
-                             GpgmeData keydata );
-GpgmeError gpgme_op_genkey ( GpgmeCtx c, const char *parms,
-                             GpgmeData pubkey, GpgmeData seckey );
-GpgmeError gpgme_op_delete ( GpgmeCtx c, const GpgmeKey key, int allow_secret);
-
-
-/* miscellaneous functions */
+/* Various functions.  */
+
+/* Check that the library fulfills the version requirement.  */
 const char *gpgme_check_version (const char *req_version);
+
+/* Check that the backend engine is available.  DEPRECATED.  */
 GpgmeError  gpgme_check_engine (void);
+
+/* Retrieve information about the backend engines.  */
 const char *gpgme_get_engine_info (void);
+
+/* Return a string describing ERR.  */
 const char *gpgme_strerror (GpgmeError err);
 
+/* Register an idle function.  */
 typedef void (*GpgmeIdleFunc)(void);
 GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle);
 
+
 /* Engine support functions.  */
+
+/* Verify that the engine implementing PROTO is installed and
+   available.  */
 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
 
+
 #ifdef __cplusplus
 }
 #endif