Move docs

svn path=/trunk/; revision=7544

ChangeLog

@@ -1,3 +1,8 @@
+@008-09-26  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/giochannel.c: Move more docs inline, and improve them
+	on the way.
+
 2008-09-25  Tor Lillqvist  <tml@novell.com>
 
 	Bug 553820 - gpoll.c: undeclared identifier

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+2008-09-26`  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/tmpl/iochannel.sgml: Move more docs inline
+
 2008-09-17  Matthias Clasen  <mclasen@redhat.com>
 
 	* === Released 2.18.1 ===

docs/reference/glib/tmpl/iochannels.sgml

@@ -184,13 +184,10 @@ Windows messages for the window in question.
 
 <!-- ##### FUNCTION g_io_channel_init ##### -->
 <para>
-Initializes a #GIOChannel struct. This is called by each of the 
+
-above functions when creating a #GIOChannel, and so is not often 
-needed by the application programmer (unless you are creating a 
-new type of #GIOChannel).
 </para>
 
-@channel: a #GIOChannel
+@channel: 
 
 
 <!-- ##### FUNCTION g_io_channel_new_file ##### -->
@@ -376,68 +373,55 @@ error domains.
 
 <!-- ##### FUNCTION g_io_channel_ref ##### -->
 <para>
-Increments the reference count of a #GIOChannel.
+
 </para>
 
-@channel: a #GIOChannel.
+@channel: 
-@Returns:  the @channel that was passed in (since 2.6)
+@Returns: 
 
 
 <!-- ##### FUNCTION g_io_channel_unref ##### -->
 <para>
-Decrements the reference count of a #GIOChannel.
+
 </para>
 
-@channel: a #GIOChannel.
+@channel: 
 
 
 <!-- ##### FUNCTION g_io_create_watch ##### -->
 <para>
-Creates a #GSource that's dispatched when @condition is met for the given
+
-@channel. For example, if condition is #G_IO_IN, the source will be dispatched
-when there's data available for reading.  g_io_add_watch() is a simpler
-interface to this same functionality, for the case where you want to add the
-source to the default main loop at the default priority.
-</para>
-<para>
-On Windows, polling a #GSource created to watch a channel for a socket
-puts the socket in non-blocking mode. This is a side-effect of the
-implementation and unavoidable.
 </para>
 
-@channel: a #GIOChannel to watch
+@channel: 
-@condition: conditions to watch for
+@condition: 
-@Returns: a new #GSource
+@Returns:
 
 
 <!-- ##### FUNCTION g_io_add_watch ##### -->
 <para>
-Adds the #GIOChannel into the
+
-<link linkend="glib-The-Main-Event-Loop">main event loop</link>
-with the default priority.
 </para>
 
-@channel: a #GIOChannel
+@channel: 
-@condition: the condition to watch for
+@condition:
-@func: the function to call when the condition is satisfied
+@func: 
-@user_data: user data to pass to @func
+@user_data: 
-@Returns: the event source id
+@Returns: 
 
 
 <!-- ##### FUNCTION g_io_add_watch_full ##### -->
 <para>
-Adds the #GIOChannel into the
+
-<link linkend="glib-The-Main-Event-Loop">main event loop</link>
-with the given priority.
 </para>
 
-@channel: a #GIOChannel
+@channel: 
-@priority: the priority of the #GIOChannel source
+@priority: 
-@condition: the condition to watch for
+@condition:
-@func: the function to call when the condition is satisfied
+@func: 
-@user_data: user data to pass to @func
+@user_data:
-@notify: the function to call when the source is removed
+@notify: 
-@Returns: the event source id
+@Returns: 
 
 
 <!-- ##### ENUM GIOCondition ##### -->

glib/giochannel.c

@@ -73,6 +73,16 @@ static GIOStatus	g_io_channel_read_line_backend	(GIOChannel  *channel,
 							 gsize       *terminator_pos,
 							 GError     **error);
 
+/**
+ * g_io_channel_init:
+ * @channel: a #GIOChannel
+ *
+ * Initializes a #GIOChannel struct. 
+ *
+ * This is called by each of the above functions when creating a 
+ * #GIOChannel, and so is not often needed by the application 
+ * programmer (unless you are creating a new type of #GIOChannel).
+ */
 void
 g_io_channel_init (GIOChannel *channel)
 {
@@ -92,6 +102,14 @@ g_io_channel_init (GIOChannel *channel)
   channel->close_on_unref = FALSE;
 }
 
+/**
+ * g_io_channel_ref:
+ * @channel: a #GIOChannel
+ *
+ * Increments the reference count of a #GIOChannel.
+ *
+ * Returns: the @channel that was passed in (since 2.6)
+ */
 GIOChannel *
 g_io_channel_ref (GIOChannel *channel)
 {
@@ -102,6 +120,12 @@ g_io_channel_ref (GIOChannel *channel)
   return channel;
 }
 
+/**
+ * g_io_channel_unref:
+ * @channel: a #GIOChannel
+ *
+ * Decrements the reference count of a #GIOChannel.
+ */
 void 
 g_io_channel_unref (GIOChannel *channel)
 {
@@ -465,6 +489,25 @@ g_io_channel_purge (GIOChannel *channel)
     }
 }
 
+/**
+ * g_io_create_watch:
+ * @channel: a #GIOChannel to watch
+ * @condition: conditions to watch for
+ *
+ * Creates a #GSource that's dispatched when @condition is met for the 
+ * given @channel. For example, if condition is #G_IO_IN, the source will 
+ * be dispatched when there's data available for reading.
+ *
+ * g_io_add_watch() is a simpler interface to this same functionality, for 
+ * the case where you want to add the source to the default main loop context 
+ * at the default priority.
+ *
+ * On Windows, polling a #GSource created to watch a channel for a socket
+ * puts the socket in non-blocking mode. This is a side-effect of the
+ * implementation and unavoidable.
+ *
+ * Returns: a new #GSource
+ */
 GSource *
 g_io_create_watch (GIOChannel   *channel,
 		   GIOCondition  condition)
@@ -474,6 +517,24 @@ g_io_create_watch (GIOChannel   *channel,
   return channel->funcs->io_create_watch (channel, condition);
 }
 
+/**
+ * g_io_add_watch_full:
+ * @channel: a #GIOChannel
+ * @priority: the priority of the #GIOChannel source
+ * @condition: the condition to watch for
+ * @func: the function to call when the condition is satisfied
+ * @user_data: user data to pass to @func
+ * @notify: the function to call when the source is removed
+ *
+ * Adds the #GIOChannel into the default main loop context
+ * with the given priority.
+ *
+ * This internally creates a main loop source using g_io_create_watch()
+ * and attaches it to the main loop context with g_source_attach().
+ * You can do these steps manuallt if you need greater control.
+ *
+ * Returns: the event source id
+ */
 guint 
 g_io_add_watch_full (GIOChannel    *channel,
 		     gint           priority,
@@ -499,6 +560,18 @@ g_io_add_watch_full (GIOChannel    *channel,
   return id;
 }
 
+/**
+ * g_io_add_watch:
+ * @channel: a #GIOChannel
+ * @condition: the condition to watch for
+ * @func: the function to call when the condition is satisfied
+ * @user_data: user data to pass to @func
+ *
+ * Adds the #GIOChannel into the default main loop context
+ * with the default priority.
+ *
+ * Returns: the event source id
+ */
 guint 
 g_io_add_watch (GIOChannel   *channel,
 		GIOCondition  condition,