[Pkg-gnupg-commit] [gnupg2] 65/205: common: Improve a function's documentation and comments.

[Daniel Kahn Gillmor]

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

dkg pushed a commit to branch experimental
in repository gnupg2.

commit 14d27b2cadf9b0bb413f2b8bad2d81c1d370c2e7
Author: Neal H. Walfield <neal at g10code.com>
Date:   Tue Feb 23 21:28:24 2016 +0100

    common: Improve a function's documentation and comments.
    
    * common/iobuf.c (iobuf_set_partial_body_length_mode): Fix
    documentation and comment.  Add an assert.
    
    --
    Signed-off-by: Neal H. Walfield <neal at g10code.com>
---
 common/iobuf.c | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/common/iobuf.c b/common/iobuf.c
index a0d48c6..9816d55 100644
--- a/common/iobuf.c
+++ b/common/iobuf.c
@@ -2515,8 +2515,16 @@ iobuf_get_fname_nonnull (iobuf_t a)
 
 
 /****************
- * enable partial block mode as described in the OpenPGP draft.
- * LEN is the first length byte on read, but ignored on writes.
+ * Enable or disable partial body length mode (RFC 4880 4.2.2.4).
+ *
+ * If LEN is 0, this disables partial block mode by popping the
+ * partial body length filter, which which must be the most recently
+ * added filter.
+ *
+ * If LEN is non-zero, it pushes a partial body length filter.  If
+ * this is a read filter, LEN must be the length byte from the first
+ * chunk and A should be position just after this first partial body
+ * length header.
  */
 void
 iobuf_set_partial_body_length_mode (iobuf_t a, size_t len)
@@ -2525,21 +2533,17 @@ iobuf_set_partial_body_length_mode (iobuf_t a, size_t len)
 
   ctx->use = a->use;
   if (!len)
+    /* Disable partial body length mode.  */
     {
       if (a->use == IOBUF_INPUT)
 	log_debug ("pop_filter called in set_partial_block_mode"
 		   " - please report\n");
-      /* XXX: This pop_filter doesn't make sense.  Since we haven't
-	 actually added the filter to the pipeline yet, why are we
-	 popping anything?  Moreover, since we don't report an error,
-	 the caller won't directly see an error.  I think that it
-	 would be better to push the filter and set a->error to
-	 GPG_ERR_BAD_DATA, but Werner thinks it's impossible for len
-	 to be 0 (but he doesn't want to remove the check just in
-	 case).  */
+
+      log_assert (a->filter == block_filter);
       pop_filter (a, block_filter, NULL);
     }
   else
+    /* Enabled partial body length mode.  */
     {
       ctx->partial = 1;
       ctx->size = 0;

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