Doc fixes

[platform/upstream/glib.git] / gio / gdatainputstream.c

diff --git a/gio/gdatainputstream.c b/gio/gdatainputstream.c
index e52348f..9d3abef 100644 (file)
--- a/gio/gdatainputstream.c
+++ b/gio/gdatainputstream.c
@@ -31,10 +31,11 @@
 /**
  * SECTION:gdatainputstream
  * @short_description: Data Input Stream
+ * @include: gio/gio.h
  * @see_also: #GInputStream
  * 
  * Data input stream implements #GInputStream and includes functions for 
- * reading data directly from an input stream.
+ * reading structured data directly from a binary input stream.
  *
  **/
 
@@ -246,8 +247,9 @@ g_data_input_stream_get_byte_order (GDataInputStream *stream)
  * 
  * Sets the newline type for the @stream.
  * 
- * TODO: is it valid to set this to G_DATA_STREAM_NEWLINE_TYPE_ANY, or
- * should it always be set to {_LF, _CR, _CR_LF}
+ * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
+ * chunk ends in "CR" we must read an additional byte to know if this is "CR" or
+ * "CR LF", and this might block if there is no more data availible.
  *  
  **/
 void
@@ -313,7 +315,7 @@ read_data (GDataInputStream  *stream,
   res = g_input_stream_read (G_INPUT_STREAM (stream),
                             buffer, size,
                             NULL, NULL);
-  g_assert (res == size);
+  g_warn_if_fail (res == size);
   return TRUE;
 }
 
@@ -327,12 +329,12 @@ read_data (GDataInputStream  *stream,
  * Reads an unsigned 8-bit/1-byte value from @stream.
  *
  * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 
- * if an error occured.
+ * if an error occurred.
  **/
 guchar
 g_data_input_stream_read_byte (GDataInputStream  *stream,
-                             GCancellable       *cancellable,
-                             GError            **error)
+                              GCancellable       *cancellable,
+                              GError            **error)
 {
   guchar c;
   
@@ -357,7 +359,7 @@ g_data_input_stream_read_byte (GDataInputStream  *stream,
  * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order().
  * 
  * Returns: a signed 16-bit/2-byte value read from @stream or %0 if 
- * an error occured.
+ * an error occurred.
  **/
 gint16
 g_data_input_stream_read_int16 (GDataInputStream  *stream,
@@ -401,12 +403,12 @@ g_data_input_stream_read_int16 (GDataInputStream  *stream,
  * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order(). 
  * 
  * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if 
- * an error occured. 
+ * an error occurred. 
  **/
 guint16
 g_data_input_stream_read_uint16 (GDataInputStream  *stream,
-                               GCancellable       *cancellable,
-                               GError            **error)
+                                GCancellable       *cancellable,
+                                GError            **error)
 {
   guint16 v;
   
@@ -449,12 +451,12 @@ g_data_input_stream_read_uint16 (GDataInputStream  *stream,
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  *   
  * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if 
- * an error occured. 
+ * an error occurred. 
  **/
 gint32
 g_data_input_stream_read_int32 (GDataInputStream  *stream,
-                              GCancellable       *cancellable,
-                              GError            **error)
+                               GCancellable       *cancellable,
+                               GError            **error)
 {
   gint32 v;
   
@@ -497,12 +499,12 @@ g_data_input_stream_read_int32 (GDataInputStream  *stream,
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if 
- * an error occured. 
+ * an error occurred. 
  **/
 guint32
 g_data_input_stream_read_uint32 (GDataInputStream  *stream,
-                               GCancellable       *cancellable,
-                               GError            **error)
+                                GCancellable       *cancellable,
+                                GError            **error)
 {
   guint32 v;
   
@@ -545,7 +547,7 @@ g_data_input_stream_read_uint32 (GDataInputStream  *stream,
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  * Returns: a signed 64-bit/8-byte value read from @stream or %0 if 
- * an error occured.  
+ * an error occurred.  
  **/
 gint64
 g_data_input_stream_read_int64 (GDataInputStream  *stream,
@@ -593,7 +595,7 @@ g_data_input_stream_read_int64 (GDataInputStream  *stream,
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if 
- * an error occured. 
+ * an error occurred. 
  **/
 guint64
 g_data_input_stream_read_uint64 (GDataInputStream  *stream,
@@ -650,7 +652,7 @@ scan_for_newline (GDataInputStream *stream,
   newline_len = 0;
   
   start = checked;
-  buffer = g_buffered_input_stream_peek_buffer (bstream, &available) + start;
+  buffer = (const char*)g_buffered_input_stream_peek_buffer (bstream, &available) + start;
   end = available;
   peeked = end - start;
 
@@ -736,8 +738,8 @@ scan_for_newline (GDataInputStream *stream,
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
- * Returns: a string with the line that was read in. Set @length to 
- * a #gsize to get the length of the read line. Returns %NULL on an error.
+ * Returns: a string with the line that was read in (including the newlines).
+ * Set @length to a #gsize to get the length of the read line. Returns %NULL on an error.
  **/
 char *
 g_data_input_stream_read_line (GDataInputStream  *stream,
@@ -797,7 +799,7 @@ g_data_input_stream_read_line (GDataInputStream  *stream,
                             NULL, NULL);
   if (length)
     *length = (gsize)found_pos;
-  g_assert (res == found_pos + newline_len);
+  g_warn_if_fail (res == found_pos + newline_len);
   line[found_pos] = 0;
   
   return line;
@@ -826,7 +828,7 @@ scan_for_chars (GDataInputStream *stream,
   found_pos = -1;
   
   start = checked;
-  buffer = g_buffered_input_stream_peek_buffer (bstream, &available) + start;
+  buffer = (const char *)g_buffered_input_stream_peek_buffer (bstream, &available) + start;
   end = available;
   peeked = end - start;
 
@@ -917,7 +919,7 @@ g_data_input_stream_read_until (GDataInputStream  *stream,
                             NULL, NULL);
   if (length)
     *length = (gsize)found_pos;
-  g_assert (res == found_pos + stop_char_len);
+  g_warn_if_fail (res == found_pos + stop_char_len);
   data_until[found_pos] = 0;
   
   return data_until;