glib r7544 - in trunk: . docs/reference docs/reference/glib/tmpl glib

[matthiasc svn gnome org]

Author: matthiasc
Date: Fri Sep 26 13:55:51 2008
New Revision: 7544
URL: http://svn.gnome.org/viewvc/glib?rev=7544&view=rev

Log:
Move docs


Modified:
   trunk/ChangeLog
   trunk/docs/reference/ChangeLog
   trunk/docs/reference/glib/tmpl/iochannels.sgml
   trunk/glib/giochannel.c

Modified: trunk/docs/reference/glib/tmpl/iochannels.sgml
==============================================================================
--- trunk/docs/reference/glib/tmpl/iochannels.sgml	(original)
+++ trunk/docs/reference/glib/tmpl/iochannels.sgml	Fri Sep 26 13:55:51 2008
@@ -184,13 +184,10 @@
 
 <!-- ##### 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 @@
 
 <!-- ##### FUNCTION g_io_channel_ref ##### -->
 <para>
-Increments the reference count of a #GIOChannel.
+
 </para>
 
- channel: a #GIOChannel.
- Returns:  the @channel that was passed in (since 2.6)
+ channel: 
+ 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
- condition: conditions to watch for
- Returns: a new #GSource
+ channel: 
+ condition: 
+ 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
- condition: the condition to watch for
- func: the function to call when the condition is satisfied
- user_data: user data to pass to @func
- Returns: the event source id
+ channel: 
+ condition:
+ func: 
+ user_data: 
+ 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
- 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
- Returns: the event source id
+ channel: 
+ priority: 
+ condition:
+ func: 
+ user_data:
+ notify: 
+ Returns: 
 
 
 <!-- ##### ENUM GIOCondition ##### -->

Modified: trunk/glib/giochannel.c
==============================================================================
--- trunk/glib/giochannel.c	(original)
+++ trunk/glib/giochannel.c	Fri Sep 26 13:55:51 2008
@@ -73,6 +73,16 @@
 							 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 @@
   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 @@
   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_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 @@
   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 @@
   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,