Fix/improve some comments in buffer.h.

isc_buffer_dup now cannot fail as a result of c73e5866c4.

lib/isc/include/isc/buffer.h

@@ -21,7 +21,7 @@
  * \brief A buffer is a region of memory, together with a set of related
  * subregions. Buffers are used for parsing and I/O operations.
  *
- * The 'used region' and the 'available' region are disjoint, and their
+ * The 'used region' and the 'available region' are disjoint, and their
  * union is the buffer's region.  The used region extends from the beginning
  * of the buffer region to the last used byte.  The available region
  * extends from one byte greater than the last used byte to the end of the
@@ -32,7 +32,7 @@
  * 'consumed region' and the 'remaining region'.  The union of these two
  * regions is the used region.  The consumed region extends from the beginning
  * of the used region to the byte before the 'current' offset (if any).  The
- * 'remaining' region the current pointer to the end of the used
+ * 'remaining' region extends from the current offset to the end of the used
  * region.  The size of the consumed region can be changed using various
  * buffer commands.  Initially, the consumed region is empty.
  *
@@ -496,7 +496,7 @@ isc_buffer_getuint8(isc_buffer_t *b);
  *
  *\li	'b' is a valid buffer.
  *
- *\li	The length of the available region of 'b' is at least 1.
+ *\li	The length of the remaining region of 'b' is at least 1.
  *
  * Ensures:
  *
@@ -515,7 +515,7 @@ isc__buffer_putuint8(isc_buffer_t *b, uint8_t val);
  * Requires:
  *\li	'b' is a valid buffer.
  *
- *\li	The length of the unused region of 'b' is at least 1
+ *\li	The length of the available region of 'b' is at least 1
  *	or the buffer has autoreallocation enabled.
  *
  * Ensures:
@@ -532,8 +532,7 @@ isc_buffer_getuint16(isc_buffer_t *b);
  *
  *\li	'b' is a valid buffer.
  *
- *\li	The length of the available region of 'b' is at least 2
+ *\li	The length of the remaining region of 'b' is at least 2.
- *	or the buffer has autoreallocation enabled.
  *
  * Ensures:
  *
@@ -553,7 +552,7 @@ isc__buffer_putuint16(isc_buffer_t *b, uint16_t val);
  * Requires:
  *\li	'b' is a valid buffer.
  *
- *\li	The length of the unused region of 'b' is at least 2
+ *\li	The length of the available region of 'b' is at least 2
  *	or the buffer has autoreallocation enabled.
  *
  * Ensures:
@@ -570,7 +569,7 @@ isc_buffer_getuint32(isc_buffer_t *b);
  *
  *\li	'b' is a valid buffer.
  *
- *\li	The length of the available region of 'b' is at least 4.
+ *\li	The length of the remaining region of 'b' is at least 4.
  *
  * Ensures:
  *
@@ -590,7 +589,7 @@ isc__buffer_putuint32(isc_buffer_t *b, uint32_t val);
  * Requires:
  *\li	'b' is a valid buffer.
  *
- *\li	The length of the unused region of 'b' is at least 4
+ *\li	The length of the available region of 'b' is at least 4
  *	or the buffer has autoreallocation enabled.
  *
  * Ensures:
@@ -607,7 +606,7 @@ isc_buffer_getuint48(isc_buffer_t *b);
  *
  *\li	'b' is a valid buffer.
  *
- *\li	The length of the available region of 'b' is at least 6.
+ *\li	The length of the remaining region of 'b' is at least 6.
  *
  * Ensures:
  *
@@ -627,7 +626,7 @@ isc__buffer_putuint48(isc_buffer_t *b, uint64_t val);
  * Requires:
  *\li	'b' is a valid buffer.
  *
- *\li	The length of the unused region of 'b' is at least 6
+ *\li	The length of the available region of 'b' is at least 6
  *	or the buffer has autoreallocation enabled.
  *
  * Ensures:
@@ -643,7 +642,7 @@ isc__buffer_putuint24(isc_buffer_t *b, uint32_t val);
  * Requires:
  *\li	'b' is a valid buffer.
  *
- *	The length of the unused region of 'b' is at least 3
+ *\li	The length of the available region of 'b' is at least 3
  *	or the buffer has autoreallocation enabled.
  *
  * Ensures:
@@ -657,11 +656,15 @@ isc__buffer_putmem(isc_buffer_t *b, const unsigned char *base,
  * \brief Copy 'length' bytes of memory at 'base' into 'b'.
  *
  * Requires:
- *\li	'b' is a valid buffer, and it has at least 'length'
+ *\li	'b' is a valid buffer.
- *	or the buffer has autoreallocation enabled.
  *
  *\li	'base' points to 'length' bytes of valid memory.
  *
+ *\li	The length of the available region of 'b' is at least 'length'
+ *	or the buffer has autoreallocation enabled.
+ *
+ * Ensures:
+ *\li	The used pointer in 'b' is advanced by 'length'.
  */
 
 void
@@ -672,9 +675,13 @@ isc__buffer_putstr(isc_buffer_t *b, const char *source);
  * Requires:
  *\li	'b' is a valid buffer.
  *
- *\li	'source' to be a valid NULL terminated string.
+ *\li	'source' is a valid NULL terminated string.
  *
- *\li	strlen(source) <= isc_buffer_available(b) || b->mctx != NULL
+ *\li	The length of the available region of 'b' is at least strlen('source')
+ *	or the buffer has autoreallocation enabled.
+ *
+ * Ensures:
+ *\li	The used pointer in 'b' is advanced by strlen('source').
  */
 
 void
@@ -685,7 +692,11 @@ isc_buffer_putdecint(isc_buffer_t *b, int64_t v);
  * Requires:
  *\li	'b' is a valid buffer.
  *
- *\li	strlen(dec(v)) <= isc_buffer_available(b) || b->mctx != NULL
+ *\li	The length of the available region of 'b' is at least strlen(dec('v'))
+ *	or the buffer has autoreallocation enabled.
+ *
+ * Ensures:
+ *\li	The used pointer in 'b' is advanced by strlen(dec('v')).
  */
 
 isc_result_t
@@ -693,13 +704,16 @@ isc_buffer_copyregion(isc_buffer_t *b, const isc_region_t *r);
 /*!<
  * \brief Copy the contents of 'r' into 'b'.
  *
+ * Notes:
+ *\li	If 'b' has autoreallocation enabled, and the length of 'r' is greater
+ *	than the length of the available region of 'b', 'b' is reallocated.
+ *
  * Requires:
  *\li	'b' is a valid buffer.
  *
  *\li	'r' is a valid region.
  *
  * Returns:
- *
  *\li	ISC_R_SUCCESS
  *\li	ISC_R_NOSPACE			The available region of 'b' is not
  *					big enough.
@@ -708,17 +722,14 @@ isc_buffer_copyregion(isc_buffer_t *b, const isc_region_t *r);
 isc_result_t
 isc_buffer_dup(isc_mem_t *mctx, isc_buffer_t **dstp, const isc_buffer_t *src);
 /*!<
- * \brief Allocate 'dst' and copy used contents  of 'src' into it
+ * \brief Allocate 'dst' and copy used contents of 'src' into it.
  *
  * Requires:
- *\li	'dstp' is not NULL and *dst is NULL
+ *\li	'dstp' is not NULL and *dst is NULL.
  *\li	'src' is a valid buffer.
  *
  * Returns:
- *
  *\li	ISC_R_SUCCESS
- *\li	ISC_R_NOSPACE			The available region of 'b' is not
- *					big enough.
  */
 
 isc_result_t
@@ -732,8 +743,9 @@ isc_buffer_printf(isc_buffer_t *b, const char *format, ...)
  *\li	The 'format' argument is a printf(3) string, with additional arguments
  *	as necessary.
  *
- *\li	If 'b' has autoreallocation enabled, and the formatted string
+ *\li	If 'b' has autoreallocation enabled, and the length of the formatted
- *	would overrun the buffer, the buffer is reallocated.
+ *	string is greater than the length of the available region of 'b', 'b'
+ *	is reallocated.
  *
  * Requires:
  *