[Pkg-gnupg-commit] [gpgme] 59/103: doc: Clarify import keys operation.

[Daniel Kahn Gillmor]

This is an automated email from the git hooks/post-receive script.

dkg pushed a commit to branch master
in repository gpgme.

commit dfb3ca85680534b3885ab04d3fba4752c5a6f998
Author: Marcus Brinkmann <marcus.brinkmann at ruhr-uni-bochum.de>
Date:   Thu Aug 10 16:50:11 2017 +0200

    doc: Clarify import keys operation.
    
    * doc/gpgme.texi (gpgme_op_import_start): Fix grammar.
    (gpgme_op_import_keys): Clarify some wording and fix result.
    * src/import.c (gpgme_op_import_keys): Clarify comment.
    
    Signed-off-by: Marcus Brinkmann <mb at g10code.com>
    GnuPG-bug-id: 3215
---
 doc/gpgme.texi | 28 +++++++++++++---------------
 src/import.c   | 13 ++++++-------
 2 files changed, 19 insertions(+), 22 deletions(-)

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 37760af..bf84629 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -4449,34 +4449,32 @@ The function @code{gpgme_op_import_start} initiates a
 
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 import could be started successfully, @code{GPG_ERR_INV_VALUE} if
- at var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
-and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
+ at var{ctx} or @var{keydata} is not a valid pointer, and
+ at code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_import_keys (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}})
-The function @code{gpgme_op_import_keys} adds the keys described by the
- at code{NULL} terminated array @var{keys} to the key ring of the crypto
-engine used by @var{ctx}.  This function is the general interface to
-move a key from one crypto engine to another as long as they are
-compatible.  In particular it is used to actually import and make keys
-permanent which have been retrieved from an external source (i.e. using
- at code{GPGME_KEYLIST_MODE_EXTERN}).  @footnote{Thus it is a replacement
-for the usual workaround of exporting and then importing a key to make
-an X.509 key permanent.}
+The function @code{gpgme_op_import_keys} adds the keys described by
+the @code{NULL} terminated array @var{keys} to the key ring of the
+crypto engine used by @var{ctx}.  It is used to actually import and
+make keys permanent which have been retrieved from an external source
+(i.e. using @code{GPGME_KEYLIST_MODE_EXTERN}).  @footnote{Thus it is a
+replacement for the usual workaround of exporting and then importing a
+key to make an X.509 key permanent.}
 
 Only keys of the currently selected protocol of @var{ctx} are
 considered for import.  Other keys specified by the @var{keys} are
 ignored.  As of now all considered keys must have been retrieved using
-the same method, that is the used key listing mode must be identical.
+the same method, i.e. the used key listing mode must be identical.
 
 After the operation completed successfully, the result can be
 retrieved with @code{gpgme_op_import_result}.
 
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 import was completed successfully, @code{GPG_ERR_INV_VALUE} if
- at var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
- at code{GPG_ERR_CONFLICT} if the key listing mode does not match, and
- at code{GPG_ERR_NO_DATA} if no keys are considered for export.
+ at var{ctx} is not a valid pointer, @code{GPG_ERR_CONFLICT} if the key
+listing mode does not match, and @code{GPG_ERR_NO_DATA} if no keys are
+considered for export.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_import_keys_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}})
diff --git a/src/import.c b/src/import.c
index 4173fe9..386ca72 100644
--- a/src/import.c
+++ b/src/import.c
@@ -392,13 +392,12 @@ gpgme_op_import_keys_start (gpgme_ctx_t ctx, gpgme_key_t *keys)
 }
 
 
-/* Import the keys from the array KEYS into the keyring.  This
-   function allows to move a key from one engine to another as long as
-   they are compatible.  In particular it is used to actually import
-   keys retrieved from an external source (i.e. using
-   GPGME_KEYLIST_MODE_EXTERN).  It replaces the old workaround of
-   exporting and then importing a key as used to make an X.509 key
-   permanent.  This function automagically does the right thing.
+/* Import the keys from the array KEYS into the keyring.  In
+   particular it is used to actually import keys retrieved from an
+   external source (i.e. using GPGME_KEYLIST_MODE_EXTERN).  It
+   replaces the old workaround of exporting and then importing a key
+   as used to make an X.509 key permanent.  This function
+   automagically does the right thing.
 
    KEYS is a NULL terminated array of gpgme key objects.  The result
    is the usual import result structure.  Only keys matching the

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/gpgme.git