improve fstrm routine documentation.

diff --git a/dnstap/dtstream.h b/dnstap/dtstream.h
index 19d1667ff4634d5ec0cef949b06663a82a6d083b..94c6b698d2c4660509640b493e9a63a5c0d08b89 100644 (file)
--- a/dnstap/dtstream.h
+++ b/dnstap/dtstream.h
@@ -225,29 +225,28 @@ struct dt_io_list_item {
 #define DNSTAP_CONTENT_TYPE             "protobuf:dnstap.Dnstap"
 
 /**
- * routine for START message, with content type.
  * This creates an FSTRM control frame of type START.
  * @param contenttype: a zero delimited string with the content type.
- *     eg. DNSTAP_CONTENT_TYPE, "protobuf:dnstap.Dnstap"
+ *     eg. use the constant DNSTAP_CONTENT_TYPE, which is defined as
+ *     "protobuf:dnstap.Dnstap", for a dnstap frame stream.
  * @param len: if a buffer is returned this is the length of that buffer.
  * @return NULL on malloc failure.  Returns a malloced buffer with the
- * protocol message.  The buffer starts with the 4byte 0 that indicates
+ * protocol message.  The buffer starts with the 4 bytes of 0 that indicate
  * a control frame.  The buffer should be sent without preceding it with
- * the 'len' variable, but straight the 0 start zeroes, and then the
- * length of the control frame itself is embedded next in the buffer,
- * with the control frame after that in the buffer.
+ * the 'len' variable (like data frames are), but straight the content of the
+ * buffer, because the lengths are included in the buffer.  This is so that
+ * the zero control indicator can be included before the control frame length.
  */
 void* fstrm_create_control_frame_start(char* contenttype, size_t* len);
 /**
- * routine for STOP message.
  * This creates an FSTRM control frame of type STOP.
  * @param len: if a buffer is returned this is the length of that buffer.
  * @return NULL on malloc failure.  Returns a malloced buffer with the
- * protocol message.  The buffer starts with the 4byte 0 that indicates
+ * protocol message.  The buffer starts with the 4 bytes of 0 that indicate
  * a control frame.  The buffer should be sent without preceding it with
- * the 'len' variable, but straight the 0 start zeroes, and then the
- * length of the control frame itself is embedded next in the buffer,
- * with the control frame after that in the buffer.
+ * the 'len' variable (like data frames are), but straight the content of the
+ * buffer, because the lengths are included in the buffer.  This is so that
+ * the zero control indicator can be included before the control frame length.
  */
 void* fstrm_create_control_frame_stop(size_t* len);