diff --git a/gio/goutputstream.c b/gio/goutputstream.c
index 60e81111f..df0807c0c 100644
--- a/gio/goutputstream.c
+++ b/gio/goutputstream.c
@@ -156,18 +156,19 @@ g_output_stream_init (GOutputStream *stream)
  * Tries to write @count bytes from @buffer into the stream. Will block
  * during the operation.
  * 
- * If count is zero returns zero and does nothing. A value of @count
+ * If count is 0, returns 0 and does nothing. A value of @count
  * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
  *
  * On success, the number of bytes written to the stream is returned.
  * It is not an error if this is not the same as the requested size, as it
- * can happen e.g. on a partial i/o error, or if there is not enough
- * storage in the stream. All writes either block until at least one byte
- * is written, so zero is never returned (unless @count is zero).
+ * can happen e.g. on a partial I/O error, or if there is not enough
+ * storage in the stream. All writes block until at least one byte
+ * is written or an error occurs; 0 is never returned (unless
+ * @count is 0).
  * 
  * If @cancellable is not NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
  * operation was partially finished when the operation was cancelled the
  * partial result will be returned, without an error.
  *