Make k5-buf.h comments consistent with coding style

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@24484 dc483132-0cff-0310-8789-dd5450dbe970

1 files changed, 54 insertions, 44 deletions

diff --git a/src/include/k5-buf.h b/src/include/k5-buf.h
index ab734e6..ccd6bd3 100644
--- a/src/include/k5-buf.h
+++ b/src/include/k5-buf.h
@@ -45,22 +45,24 @@
 #include <unistd.h>
 #endif
 
-/* The k5buf module is intended to allow multi-step string
-   construction in a fixed or dynamic buffer without the need to check
-   for a failure at each step (and without aborting on malloc
-   failure).  If an allocation failure occurs or if the fixed buffer
-   runs out of room, the error will be discovered when the caller
-   retrieves the C string value or checks the length of the resulting
-   buffer.
-
-   k5buf structures are stack-allocated, but are intended to be
-   opaque, so do not access the fields directly.  This is a tool, not
-   a way of life, so do not put k5buf structure pointers into the
-   public API or into significant internal APIs. */
-
-/* We must define the k5buf structure here to allow stack allocation.
-   The structure is intended to be opaque, so the fields have funny
-   names. */
+/*
+ * The k5buf module is intended to allow multi-step string construction in a
+ * fixed or dynamic buffer without the need to check for a failure at each step
+ * (and without aborting on malloc failure).  If an allocation failure occurs
+ * or if the fixed buffer runs out of room, the error will be discovered when
+ * the caller retrieves the C string value or checks the length of the
+ * resulting buffer.
+ *
+ * k5buf structures are stack-allocated, but are intended to be opaque, so do
+ * not access the fields directly.  This is a tool, not a way of life, so do
+ * not put k5buf structure pointers into the public API or into significant
+ * internal APIs.
+ */
+
+/*
+ * We must define the k5buf structure here to allow stack allocation.  The
+ * structure is intended to be opaque, so the fields have funny names.
+ */
 struct k5buf {
     int xx_buftype;
     char *xx_data;
@@ -68,20 +70,22 @@ struct k5buf {
     size_t xx_len;
 };
 
-/** Initialize a k5buf using a fixed-sized, existing buffer.  SPACE
-   must be more than zero, or an assertion failure will result. */
+/** Initialize a k5buf using a fixed-sized, existing buffer.  SPACE must be
+ * more than zero, or an assertion failure will result. */
 void krb5int_buf_init_fixed(struct k5buf *buf, char *data, size_t space);
 
-/** Initialize a k5buf using an internally allocated dynamic buffer.
-   The buffer contents must be freed with krb5int_free_buf. */
+/** Initialize a k5buf using an internally allocated dynamic buffer.  The
+ * buffer contents must be freed with krb5int_free_buf. */
 void krb5int_buf_init_dynamic(struct k5buf *buf);
 
 /** Add a C string to BUF. */
 void krb5int_buf_add(struct k5buf *buf, const char *data);
 
-/** Add a counted set of bytes to BUF.  It is okay for DATA[0..LEN-1]
-   to contain null bytes if you are prepared to deal with that in the
-   output (use krb5int_buf_len to retrieve the length of the output). */
+/**
+ * Add a counted set of bytes to BUF.  It is okay for DATA[0..LEN-1]
+ * to contain null bytes if you are prepared to deal with that in the
+ * output (use krb5int_buf_len to retrieve the length of the output).
+ */
 void krb5int_buf_add_len(struct k5buf *buf, const char *data, size_t len);
 
 /** Add sprintf-style formatted data to BUF. */
@@ -92,36 +96,42 @@ void krb5int_buf_add_fmt(struct k5buf *buf, const char *fmt, ...)
     ;
 
 /** Truncate BUF.  LEN must be between 0 and the existing buffer
-   length, or an assertion failure will result. */
+ * length, or an assertion failure will result. */
 void krb5int_buf_truncate(struct k5buf *buf, size_t len);
 
-/** Retrieve the byte array value of BUF, or NULL if there has been an
-   allocation failure or the fixed buffer ran out of room.
+/**
+ * Retrieve the byte array value of BUF, or NULL if there has been an
+ * allocation failure or the fixed buffer ran out of room.
 
-   The byte array will be a C string unless binary data was added with
-   krb5int_buf_add_len; it will be null-terminated regardless.
-   Modifying the byte array does not invalidate the buffer, as long as
-   its length is not changed.
+ * The byte array will be a C string unless binary data was added with
+ * krb5int_buf_add_len; it will be null-terminated regardless.
+ * Modifying the byte array does not invalidate the buffer, as long as
+ * its length is not changed.
 
-   For a fixed buffer, the return value will always be equal to the
-   passed-in value of DATA at initialization time if it is not NULL.
+ * For a fixed buffer, the return value will always be equal to the
+ * passed-in value of DATA at initialization time if it is not NULL.
 
-   For a dynamic buffer, any buffer modification operation except
-   krb5int_buf_truncate may invalidate the byte array address. */
+ * For a dynamic buffer, any buffer modification operation except
+ * krb5int_buf_truncate may invalidate the byte array address.
+ */
 char *krb5int_buf_data(struct k5buf *buf);
 
-/** Retrieve the length of BUF, or -1 if there has been an allocation
-   failure or the fixed buffer ran out of room.  The length is equal
-   to strlen(krb5int_buf_data(buf)) unless binary data was added with
-   krb5int_buf_add_len. */
+/**
+ * Retrieve the length of BUF, or -1 if there has been an allocation
+ * failure or the fixed buffer ran out of room.  The length is equal
+ * to strlen(krb5int_buf_data(buf)) unless binary data was added with
+ * krb5int_buf_add_len.
+ */
 ssize_t krb5int_buf_len(struct k5buf *buf);
 
-/** Free the storage used in the dynamic buffer BUF.  The caller may
-   choose to take responsibility for freeing the return value of
-   krb5int_buf_data instead of using this function.  If BUF is a fixed
-   buffer, an assertion failure will result.  It is unnecessary
-   (though harmless) to free a buffer after an error is detected; the
-   storage will already have been freed in that case. */
+/**
+ * Free the storage used in the dynamic buffer BUF.  The caller may
+ * choose to take responsibility for freeing the return value of
+ * krb5int_buf_data instead of using this function.  If BUF is a fixed
+ * buffer, an assertion failure will result.  It is unnecessary
+ * (though harmless) to free a buffer after an error is detected; the
+ * storage will already have been freed in that case.
+ */
 void krb5int_free_buf(struct k5buf *buf);
 
 #endif /* K5_BUF_H */