Move the WPACKET documentation comments to packet_locl.h

The PACKET documentation is already in packet_locl.h so it makes sense to
have the WPACKET documentation there as well.

Reviewed-by: Rich Salz <rsalz@openssl.org>

2 files changed, 87 insertions, 69 deletions

diff --git a/ssl/packet.c b/ssl/packet.c
index 69ad1009dc..4823b16a6e 100644
--- a/ssl/packet.c
+++ b/ssl/packet.c
@@ -11,10 +11,6 @@
 
 #define DEFAULT_BUF_SIZE    256
 
-/*
- * Allocate bytes in the WPACKET for the output. This reserves the bytes
- * and count them as "written", but doesn't actually do the writing.
- */
 int WPACKET_allocate_bytes(WPACKET *pkt, size_t len, unsigned char **allocbytes)
 {
     if (pkt->subs == NULL || len == 0)
@@ -62,12 +58,6 @@ static size_t maxmaxsize(size_t lenbytes)
         return ((size_t)1 << (lenbytes * 8)) - 1 + lenbytes;
 }
 
-/*
- * Initialise a WPACKET with the buffer in |buf|. The buffer must exist
- * for the whole time that the WPACKET is being used. Additionally |lenbytes| of
- * data is preallocated at the start of the buffer to store the length of the
- * WPACKET once we know it.
- */
 int WPACKET_init_len(WPACKET *pkt, BUF_MEM *buf, size_t lenbytes)
 {
     /* Sanity check */
@@ -98,23 +88,11 @@ int WPACKET_init_len(WPACKET *pkt, BUF_MEM *buf, size_t lenbytes)
     return 1;
 }
 
-/*
- * Same as WPACKET_init_len except there is no preallocation of the WPACKET
- * length.
- */
 int WPACKET_init(WPACKET *pkt, BUF_MEM *buf)
 {
     return WPACKET_init_len(pkt, buf, 0);
 }
 
-/*
- * Set the WPACKET length, and the location for where we should write that
- * length. Normally this will be at the start of the WPACKET, and therefore
- * the WPACKET would have been initialised via WPACKET_init_len(). However there
- * is the possibility that the length needs to be written to some other location
- * other than the start of the WPACKET. In that case init via WPACKET_init() and
- * then set the location for the length using this function.
- */
 int WPACKET_set_packet_len(WPACKET *pkt, unsigned char *packet_len,
                            size_t lenbytes)
 {
@@ -196,12 +174,6 @@ static int wpacket_intern_close(WPACKET *pkt)
     return 1;
 }
 
-/*
- * Closes the most recent sub-packet. It also writes out the length of the
- * packet to the required location (normally the start of the WPACKET) if
- * appropriate. The top level WPACKET should be closed using WPACKET_finish()
- * instead of this function.
- */
 int WPACKET_close(WPACKET *pkt)
 {
     if (pkt->subs == NULL || pkt->subs->parent == NULL)
@@ -210,10 +182,6 @@ int WPACKET_close(WPACKET *pkt)
     return wpacket_intern_close(pkt);
 }
 
-/*
- * The same as WPACKET_close() but only for the top most WPACKET. Additionally
- * frees memory resources for this WPACKET.
- */
 int WPACKET_finish(WPACKET *pkt)
 {
     int ret;
@@ -230,10 +198,6 @@ int WPACKET_finish(WPACKET *pkt)
     return ret;
 }
 
-/*
- * Initialise a new sub-packet. Additionally |lenbytes| of data is preallocated
- * at the start of the sub-packet to store its length once we know it.
- */
 int WPACKET_start_sub_packet_len(WPACKET *pkt, size_t lenbytes)
 {
     WPACKET_SUB *sub;
@@ -262,21 +226,11 @@ int WPACKET_start_sub_packet_len(WPACKET *pkt, size_t lenbytes)
     return 1;
 }
 
-/*
- * Same as WPACKET_get_sub_packet_len() except no bytes are pre-allocated for
- * the sub-packet length.
- */
 int WPACKET_start_sub_packet(WPACKET *pkt)
 {
     return WPACKET_start_sub_packet_len(pkt, 0);
 }
 
-/*
- * Write the value stored in |val| into the WPACKET. The value will consome
- * |bytes| amount of storage. An error will occur if |val| cannot be accommdated
- * in |bytes| storage, e.g. attempting to write the value 256 into 1 byte will
- * fail.
- */
 int WPACKET_put_bytes(WPACKET *pkt, unsigned int val, size_t bytes)
 {
     unsigned char *data;
@@ -299,7 +253,6 @@ int WPACKET_put_bytes(WPACKET *pkt, unsigned int val, size_t bytes)
     return 1;
 }
 
-/* Set a maximum size that we will not allow the WPACKET to grow beyond */
 int WPACKET_set_max_size(WPACKET *pkt, size_t maxsize)
 {
     WPACKET_SUB *sub;
@@ -323,9 +276,6 @@ int WPACKET_set_max_size(WPACKET *pkt, size_t maxsize)
     return 1;
 }
 
-/*
- * Copy |len| bytes of data from |*src| into the WPACKET.
- */
 int WPACKET_memcpy(WPACKET *pkt, const void *src, size_t len)
 {
     unsigned char *dest;
@@ -341,10 +291,6 @@ int WPACKET_memcpy(WPACKET *pkt, const void *src, size_t len)
     return 1;
 }
 
-/*
- * Copy |len| bytes of data from |*src| into the WPACKET and prefix with its
- * length (consuming |lenbytes| of data for the length)
- */
 int WPACKET_sub_memcpy(WPACKET *pkt, const void *src, size_t len, size_t lenbytes)
 {
     if (!WPACKET_start_sub_packet_len(pkt, lenbytes)
@@ -355,10 +301,6 @@ int WPACKET_sub_memcpy(WPACKET *pkt, const void *src, size_t len, size_t lenbyte
     return 1;
 }
 
-/*
- * Return the total number of bytes written so far to the underlying buffer
- * including any storage allocated for length bytes
- */
 int WPACKET_get_total_written(WPACKET *pkt, size_t *written)
 {
     if (written == NULL)
@@ -369,10 +311,6 @@ int WPACKET_get_total_written(WPACKET *pkt, size_t *written)
     return 1;
 }
 
-/*
- * Returns the length of the last sub-packet. This excludes any bytes allocated
- * for the length itself.
- */
 int WPACKET_get_length(WPACKET *pkt, size_t *len)
 {
     if (pkt->subs == NULL || len == NULL)
@@ -383,9 +321,6 @@ int WPACKET_get_length(WPACKET *pkt, size_t *len)
     return 1;
 }
 
-/*
- * Release resources in a WPACKET if a failure has occurred.
- */
 void WPACKET_cleanup(WPACKET *pkt)
 {
     WPACKET_SUB *sub, *parent;
diff --git a/ssl/packet_locl.h b/ssl/packet_locl.h
index acbd966121..255a8a508a 100644
--- a/ssl/packet_locl.h
+++ b/ssl/packet_locl.h
@@ -583,43 +583,126 @@ struct wpacket_st {
     /* Number of bytes written so far */
     size_t written;
 
-    /*
-     * Maximum number of bytes we will allow to be written to this WPACKET.
-     */
+    /* Maximum number of bytes we will allow to be written to this WPACKET */
     size_t maxsize;
 
-    /* Our sub-packets (always at least one if not closed) */
+    /* Our sub-packets (always at least one if not finished) */
     WPACKET_SUB *subs;
 };
 
 /* Flags */
+
+/* Default */
 #define OPENSSL_WPACKET_FLAGS_NONE                      0
+
 /* Error on WPACKET_close() if no data written to the WPACKET */
 #define OPENSSL_WPACKET_FLAGS_NON_ZERO_LENGTH           1
+
 /*
  * Abandon all changes on WPACKET_close() if no data written to the WPACKET,
  * i.e. this does not write out a zero packet length
  */
 #define OPENSSL_WPACKET_FLAGS_ABANDON_ON_ZERO_LENGTH    2
 
+
+/*
+ * Initialise a WPACKET with the buffer in |buf|. The buffer must exist
+ * for the whole time that the WPACKET is being used. Additionally |lenbytes| of
+ * data is preallocated at the start of the buffer to store the length of the
+ * WPACKET once we know it.
+ */
 int WPACKET_init_len(WPACKET *pkt, BUF_MEM *buf, size_t lenbytes);
+
+/*
+ * Same as WPACKET_init_len except there is no preallocation of the WPACKET
+ * length.
+ */
 int WPACKET_init(WPACKET *pkt, BUF_MEM *buf);
+
+/*
+ * Set the flags to be applied to the current sub-packet
+ */
 int WPACKET_set_flags(WPACKET *pkt, unsigned int flags);
+
+/*
+ * Set the WPACKET length, and the location for where we should write that
+ * length. Normally this will be at the start of the WPACKET, and therefore
+ * the WPACKET would have been initialised via WPACKET_init_len(). However there
+ * is the possibility that the length needs to be written to some other location
+ * other than the start of the WPACKET. In that case init via WPACKET_init() and
+ * then set the location for the length using this function.
+ */
 int WPACKET_set_packet_len(WPACKET *pkt, unsigned char *packet_len,
                            size_t lenbytes);
+
+/*
+ * Closes the most recent sub-packet. It also writes out the length of the
+ * packet to the required location (normally the start of the WPACKET) if
+ * appropriate. The top level WPACKET should be closed using WPACKET_finish()
+ * instead of this function.
+ */
 int WPACKET_close(WPACKET *pkt);
+
+/*
+ * The same as WPACKET_close() but only for the top most WPACKET. Additionally
+ * frees memory resources for this WPACKET.
+ */
 int WPACKET_finish(WPACKET *pkt);
+
+/*
+ * Initialise a new sub-packet. Additionally |lenbytes| of data is preallocated
+ * at the start of the sub-packet to store its length once we know it.
+ */
 int WPACKET_start_sub_packet_len(WPACKET *pkt, size_t lenbytes);
+
+/*
+ * Same as WPACKET_start_sub_packet_len() except no bytes are pre-allocated for
+ * the sub-packet length.
+ */
 int WPACKET_start_sub_packet(WPACKET *pkt);
+
+/*
+ * Allocate bytes in the WPACKET for the output. This reserves the bytes
+ * and counts them as "written", but doesn't actually do the writing. A pointer
+ * to the allocated bytes is stored in |*allocbytes|.
+ */
 int WPACKET_allocate_bytes(WPACKET *pkt, size_t bytes,
                            unsigned char **allocbytes);
+
+/*
+ * Write the value stored in |val| into the WPACKET. The value will consume
+ * |bytes| amount of storage. An error will occur if |val| cannot be
+ * accommodated in |bytes| storage, e.g. attempting to write the value 256 into
+ * 1 byte will fail.
+ */
 int WPACKET_put_bytes(WPACKET *pkt, unsigned int val, size_t bytes);
+
+/* Set a maximum size that we will not allow the WPACKET to grow beyond */
 int WPACKET_set_max_size(WPACKET *pkt, size_t maxsize);
+
+/* Copy |len| bytes of data from |*src| into the WPACKET. */
 int WPACKET_memcpy(WPACKET *pkt, const void *src, size_t len);
+
+/*
+ * Copy |len| bytes of data from |*src| into the WPACKET and prefix with its
+ * length (consuming |lenbytes| of data for the length)
+ */
 int WPACKET_sub_memcpy(WPACKET *pkt, const void *src, size_t len,
                        size_t lenbytes);
+
+/*
+ * Return the total number of bytes written so far to the underlying buffer
+ * including any storage allocated for length bytes
+ */
 int WPACKET_get_total_written(WPACKET *pkt, size_t *written);
+
+/*
+ * Returns the length of the current sub-packet. This excludes any bytes
+ * allocated for the length itself.
+ */
 int WPACKET_get_length(WPACKET *pkt, size_t *len);
+
+/* Release resources in a WPACKET if a failure has occurred. */
 void WPACKET_cleanup(WPACKET *pkt);
 
 # ifdef __cplusplus