Improve buf.c comments, from zinovik.

ok stsp

2 files changed, 52 insertions, 43 deletions

diff --git a/usr.bin/cvs/buf.c b/usr.bin/cvs/buf.c
index c54260be977..a21676c9848 100644
--- a/usr.bin/cvs/buf.c
+++ b/usr.bin/cvs/buf.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: buf.c,v 1.79 2010/09/08 15:13:39 tobias Exp $	*/
+/*	$OpenBSD: buf.c,v 1.80 2010/09/08 20:49:11 nicm Exp $	*/
 /*
  * Copyright (c) 2003 Jean-Francois Brousseau <jfb@openbsd.org>
  * All rights reserved.
@@ -40,6 +40,7 @@
 #define BUF_INCR	128
 
 struct buf {
+	/* buffer handle, buffer size, and data length */
 	u_char	*cb_buf;
 	size_t	 cb_size;
 	size_t	 cb_len;
@@ -49,6 +50,11 @@ struct buf {
 
 static void	buf_grow(BUF *, size_t);
 
+/*
+ * Create a new buffer structure and return a pointer to it.  This structure
+ * uses dynamically-allocated memory and must be freed with buf_free(), once
+ * the buffer is no longer needed.
+ */
 BUF *
 buf_alloc(size_t len)
 {
@@ -67,6 +73,11 @@ buf_alloc(size_t len)
 	return (b);
 }
 
+/*
+ * Open the file specified by <path> and load all of its contents into a
+ * buffer.
+ * Returns the loaded buffer.
+ */
 BUF *
 buf_load(const char *path)
 {
@@ -112,6 +123,11 @@ buf_free(BUF *b)
 	xfree(b);
 }
 
+/*
+ * Free the buffer <b>'s structural information but do not free the contents
+ * of the buffer.  Instead, they are returned and should be freed later using
+ * xfree().
+ */
 void *
 buf_release(BUF *b)
 {
@@ -122,6 +138,9 @@ buf_release(BUF *b)
 	return (tmp);
 }
 
+/*
+ * Append a single character <c> to the end of the buffer <b>.
+ */
 void
 buf_putc(BUF *b, int c)
 {
@@ -134,12 +153,20 @@ buf_putc(BUF *b, int c)
 	b->cb_len++;
 }
 
+/*
+ * Append a C-string <str> to the end of the buffer <b>.
+ */
 void
 buf_puts(BUF *b, const char *str)
 {
 	buf_append(b, str, strlen(str));
 }
 
+/*
+ * Append <len> bytes of data pointed to by <data> to the buffer <b>.  If the
+ * buffer is too small to accept all data, it will get resized to an
+ * appropriate size to accept all data.
+ */
 void
 buf_append(BUF *b, const void *data, size_t len)
 {
@@ -156,12 +183,18 @@ buf_append(BUF *b, const void *data, size_t len)
 	b->cb_len += len;
 }
 
+/*
+ * Returns the size of the buffer that is being used.
+ */
 size_t
 buf_len(BUF *b)
 {
 	return (b->cb_len);
 }
 
+/*
+ * Write the contents of the buffer <b> to the specified <fd>
+ */
 int
 buf_write_fd(BUF *b, int fd)
 {
@@ -170,6 +203,10 @@ buf_write_fd(BUF *b, int fd)
 	return (0);
 }
 
+/*
+ * Write the contents of the buffer <b> to the file whose path is given in
+ * <path>.  If the file does not exist, it is created with mode <mode>.
+ */
 int
 buf_write(BUF *b, const char *path, mode_t mode)
 {
@@ -195,6 +232,12 @@ open:
 	return (0);
 }
 
+/*
+ * Write the contents of the buffer <b> to a temporary file whose path is
+ * specified using <template> (see mkstemp.3). If <tv> is specified file
+ * access and modification time is set to <tv>.
+ * NB. This function will modify <template>, as per mkstemp
+ */
 int
 buf_write_stmp(BUF *b, char *template, struct timeval *tv)
 {
@@ -237,8 +280,6 @@ buf_differ(const BUF *b1, const BUF *b2)
 }
 
 /*
- * buf_grow()
- *
  * Grow the buffer <b> by <len> bytes.  The contents are unchanged by this
  * operation regardless of the result.
  */
diff --git a/usr.bin/rcs/buf.c b/usr.bin/rcs/buf.c
index 5c0f90f0e84..39073187298 100644
--- a/usr.bin/rcs/buf.c
+++ b/usr.bin/rcs/buf.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: buf.c,v 1.17 2010/09/08 15:13:39 tobias Exp $	*/
+/*	$OpenBSD: buf.c,v 1.18 2010/09/08 20:49:11 nicm Exp $	*/
 /*
  * Copyright (c) 2003 Jean-Francois Brousseau <jfb@openbsd.org>
  * All rights reserved.
@@ -53,11 +53,9 @@ struct buf {
 static void	buf_grow(BUF *, size_t);
 
 /*
- * buf_alloc()
- *
  * Create a new buffer structure and return a pointer to it.  This structure
- * uses dynamically-allocated memory and must be freed with buf_free(),
- * once the buffer is no longer needed.
+ * uses dynamically-allocated memory and must be freed with buf_free(), once
+ * the buffer is no longer needed.
  */
 BUF *
 buf_alloc(size_t len)
@@ -78,8 +76,6 @@ buf_alloc(size_t len)
 }
 
 /*
- * buf_load()
- *
  * Open the file specified by <path> and load all of its contents into a
  * buffer.
  * Returns the loaded buffer on success or NULL on failure.
@@ -147,11 +143,9 @@ buf_free(BUF *b)
 }
 
 /*
- * buf_release()
- *
  * Free the buffer <b>'s structural information but do not free the contents
  * of the buffer.  Instead, they are returned and should be freed later using
- * free().
+ * xfree().
  */
 void *
 buf_release(BUF *b)
@@ -163,9 +157,6 @@ buf_release(BUF *b)
 	return (tmp);
 }
 
-/*
- * buf_get()
- */
 u_char *
 buf_get(BUF *b)
 {
@@ -173,8 +164,6 @@ buf_get(BUF *b)
 }
 
 /*
- * buf_empty()
- *
  * Empty the contents of the buffer <b> and reset pointers.
  */
 void
@@ -185,8 +174,6 @@ buf_empty(BUF *b)
 }
 
 /*
- * buf_putc()
- *
  * Append a single character <c> to the end of the buffer <b>.
  */
 void
@@ -202,10 +189,7 @@ buf_putc(BUF *b, int c)
 }
 
 /*
- * buf_getc()
- *
  * Return u_char at buffer position <pos>.
- *
  */
 u_char
 buf_getc(BUF *b, size_t pos)
@@ -214,11 +198,9 @@ buf_getc(BUF *b, size_t pos)
 }
 
 /*
- * buf_append()
- *
  * Append <len> bytes of data pointed to by <data> to the buffer <b>.  If the
- * buffer is too small to accept all data, it
- * will get resized to an appropriate size to accept all data.
+ * buffer is too small to accept all data, it will get resized to an
+ * appropriate size to accept all data.
  * Returns the number of bytes successfully appended to the buffer.
  */
 size_t
@@ -239,10 +221,6 @@ buf_append(BUF *b, const void *data, size_t len)
 	return (rlen);
 }
 
-/*
- * buf_fappend()
- *
- */
 size_t
 buf_fappend(BUF *b, const char *fmt, ...)
 {
@@ -264,8 +242,6 @@ buf_fappend(BUF *b, const char *fmt, ...)
 }
 
 /*
- * buf_len()
- *
  * Returns the size of the buffer that is being used.
  */
 size_t
@@ -275,8 +251,6 @@ buf_len(BUF *b)
 }
 
 /*
- * buf_write_fd()
- *
  * Write the contents of the buffer <b> to the specified <fd>
  */
 int
@@ -305,8 +279,6 @@ buf_write_fd(BUF *b, int fd)
 }
 
 /*
- * buf_write()
- *
  * Write the contents of the buffer <b> to the file whose path is given in
  * <path>.  If the file does not exist, it is created with mode <mode>.
  */
@@ -336,11 +308,9 @@ buf_write(BUF *b, const char *path, mode_t mode)
 }
 
 /*
- * buf_write_stmp()
- *
  * Write the contents of the buffer <b> to a temporary file whose path is
- * specified using <template> (see mkstemp.3). NB. This function will modify
- * <template>, as per mkstemp
+ * specified using <template> (see mkstemp.3).
+ * NB. This function will modify <template>, as per mkstemp
  */
 void
 buf_write_stmp(BUF *b, char *template)
@@ -361,8 +331,6 @@ buf_write_stmp(BUF *b, char *template)
 }
 
 /*
- * buf_grow()
- *
  * Grow the buffer <b> by <len> bytes.  The contents are unchanged by this
  * operation regardless of the result.
  */