/soc/2013/ankitkv/gobjectification: 1eedcfcb91ef: Added doc comm...

[Ankit Vani]

Changeset: 1eedcfcb91efe7ca90617753f06a142f15973c50
Author:	 Ankit Vani <a at nevitus.org>
Date:	 2013-11-18 00:47 +0530
Branch:	 soc.2013.gobjectification
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/1eedcfcb91ef

Description:

Added doc comments for new PurpleCircularBuffer functions. Removed purple_circular_buffer_get_input from public API.

diffstat:

 libpurple/circularbuffer.c |  22 ++++++++--------
 libpurple/circularbuffer.h |  58 ++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 60 insertions(+), 20 deletions(-)

diffs (142 lines):

diff --git a/libpurple/circularbuffer.c b/libpurple/circularbuffer.c
--- a/libpurple/circularbuffer.c
+++ b/libpurple/circularbuffer.c
@@ -230,6 +230,17 @@ purple_circular_buffer_set_grow_size(Pur
 	g_object_notify(G_OBJECT(buffer), "grow-size");
 }
 
+static const gchar *
+purple_circular_buffer_get_input(const PurpleCircularBuffer *buffer) {
+	PurpleCircularBufferPrivate *priv = NULL;
+
+	g_return_val_if_fail(PURPLE_IS_CIRCULAR_BUFFER(buffer), NULL);
+
+	priv = PURPLE_CIRCULAR_BUFFER_GET_PRIVATE(buffer);
+
+	return priv->input;
+}
+
 /******************************************************************************
  * Object Stuff
  *****************************************************************************/
@@ -438,17 +449,6 @@ purple_circular_buffer_get_used(const Pu
 }
 
 const gchar *
-purple_circular_buffer_get_input(const PurpleCircularBuffer *buffer) {
-	PurpleCircularBufferPrivate *priv = NULL;
-
-	g_return_val_if_fail(PURPLE_IS_CIRCULAR_BUFFER(buffer), NULL);
-
-	priv = PURPLE_CIRCULAR_BUFFER_GET_PRIVATE(buffer);
-
-	return priv->input;
-}
-
-const gchar *
 purple_circular_buffer_get_output(const PurpleCircularBuffer *buffer) {
 	PurpleCircularBufferPrivate *priv = NULL;
 
diff --git a/libpurple/circularbuffer.h b/libpurple/circularbuffer.h
--- a/libpurple/circularbuffer.h
+++ b/libpurple/circularbuffer.h
@@ -69,15 +69,15 @@ GType purple_circular_buffer_get_type(vo
  *                 is appended and every time more space is needed.  Pass in
  *                 "0" to use the default of 256 bytes.
  *
- * @return The new PurpleCircBuffer.
+ * @return The new PurpleCircularBuffer.
  */
 PurpleCircularBuffer *purple_circular_buffer_new(gsize growsize);
 
 /**
- * Append data to the PurpleCircBuffer.  This will grow the internal
+ * Append data to the PurpleCircularBuffer.  This will grow the internal
  * buffer to fit the added data, if needed.
  *
- * @param buf The PurpleCircBuffer to which to append the data
+ * @param buf The PurpleCircularBuffer to which to append the data
  * @param src pointer to the data to copy into the buffer
  * @param len number of bytes to copy into the buffer
  */
@@ -85,22 +85,22 @@ void purple_circular_buffer_append(Purpl
 
 /**
  * Determine the maximum number of contiguous bytes that can be read from the
- * PurpleCircBuffer.
+ * PurpleCircularBuffer.
  * Note: This may not be the total number of bytes that are buffered - a
  * subsequent call after calling purple_circular_buffer_mark_read() may indicate
  * more data is available to read.
  *
- * @param buf the PurpleCircBuffer for which to determine the maximum contiguous
- *            bytes that can be read.
+ * @param buf the PurpleCircularBuffer for which to determine the maximum
+ *            contiguous bytes that can be read.
  *
- * @return the number of bytes that can be read from the PurpleCircBuffer
+ * @return the number of bytes that can be read from the PurpleCircularBuffer
  */
 gsize purple_circular_buffer_get_max_read(const PurpleCircularBuffer *buf);
 
 /**
  * Mark the number of bytes that have been read from the buffer.
  *
- * @param buf The PurpleCircBuffer to mark bytes read from
+ * @param buf The PurpleCircularBuffer to mark bytes read from
  * @param len The number of bytes to mark as read
  *
  * @return TRUE if we successfully marked the bytes as having been read, FALSE
@@ -108,11 +108,51 @@ gsize purple_circular_buffer_get_max_rea
  */
 gboolean purple_circular_buffer_mark_read(PurpleCircularBuffer *buf, gsize len);
 
+/**
+ * Increases the buffer size by a multiple of grow size, so that it can hold at
+ * least 'len' bytes.
+ *
+ * @param buffer The PurpleCircularBuffer to grow.
+ * @param len    The number of bytes the buffer should be able to hold.
+ */
 void purple_circular_buffer_grow(PurpleCircularBuffer *buffer, gsize len);
+
+/**
+ * Returns the number of bytes by which the buffer grows when more space is
+ * needed.
+ *
+ * @param buffer The PurpleCircularBuffer from which to get grow size.
+ *
+ * @return The grow size of the buffer.
+ */
 gsize purple_circular_buffer_get_grow_size(const PurpleCircularBuffer *buffer);
+
+/**
+ * Returns the number of bytes of this buffer that contain unread data.
+ *
+ * @param buffer The PurpleCircularBuffer from which to get used count.
+ *
+ * @return The number of bytes that contain unread data.
+ */
 gsize purple_circular_buffer_get_used(const PurpleCircularBuffer *buffer);
-const gchar *purple_circular_buffer_get_input(const PurpleCircularBuffer *buffer);
+
+/**
+ * Returns the output pointer of the buffer, where unread data is available.
+ * Use purple_circular_buffer_get_max_read() to determine the number of
+ * contiguous bytes that can be read from this output. After reading the data,
+ * call purple_circular_buffer_mark_read() to mark the retrieved data as read.
+ *
+ * @param buffer The PurpleCircularBuffer from which to get the output pointer.
+ *
+ * @return The output pointer for the buffer.
+ */
 const gchar *purple_circular_buffer_get_output(const PurpleCircularBuffer *buffer);
+
+/**
+ * Resets the buffer contents.
+ *
+ * @param buffer The PurpleCircularBuffer to reset.
+ */
 void purple_circular_buffer_reset(PurpleCircularBuffer *buffer);
 
 G_END_DECLS