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>

1 files changed, 87 insertions, 4 deletions

diff --git a/ssl/packet_locl.h b/ssl/packet_locl.h
index acbd966..255a8a5 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