[gnio] Add docs to GSocketConnection

[Alexander Larsson <alexl src gnome org>]

commit da63c7108f9a78df883a7c4baeaf314050bf7e78
Author: Alexander Larsson <alexl redhat com>
Date:   Fri May 15 12:39:51 2009 +0200

    Add docs to GSocketConnection
---
 gio/gsocketconnection.c |   75 ++++++++++++++++++++++++++++++++++++++++++-----
 gio/gsocketconnection.h |   28 ++++++++++++++----
 2 files changed, 89 insertions(+), 14 deletions(-)

diff --git a/gio/gsocketconnection.c b/gio/gsocketconnection.c
index 4ec8045..df9eb0d 100644
--- a/gio/gsocketconnection.c
+++ b/gio/gsocketconnection.c
@@ -1,7 +1,8 @@
-/* GNIO - GLib Network Layer of GIO
+/* GIO - GLib Input, Output and Streaming Library
  *
  * Copyright © 2008 Christian Kellner, Samuel Cormier-Iijima
  *           © 2008 codethink
+ * Copyright © 2009 Red Hat, Inc
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -21,16 +22,10 @@
  * Authors: Christian Kellner <gicmo gnome org>
  *          Samuel Cormier-Iijima <sciyoshi gmail com>
  *          Ryan Lortie <desrt desrt ca>
+ *          Alexander Larsson <alexl redhat com>
  */
 
-/* TODO: On glib merge, switch this */
 #include "config.h"
-#if 0
-#include "glibintl.h"
-#else
-#include <glib/gi18n-lib.h>
-#define P_(String) _(String)
-#endif
 
 #include "gsocketconnection.h"
 
@@ -41,6 +36,28 @@
 #include "gunixconnection.h"
 #include "gtcpconnection.h"
 
+/**
+ * SECTION:gsocketconnection
+ * @short_description: High-level socket connection stream
+ * @include: gio/gio.h
+ * @see_also: #GIOStream, #GSocketClient, #GSocketListener
+ *
+ * #GSocketConnection is a #GIOStream for a connected socket. They
+ * can be created either by #GSocketClient when connecting to a host,
+ * or by #GSocketListener when accepting a new client.
+ *
+ * The type of the #GSocketConnection object returned from these calls depends
+ * on the type of the underlying socket that is in use. For instance, for a
+ * TCP/IP connection it will be a #GTcpConnection.
+ *
+ * Chosing what type of object to construct is done with the socket connection
+ * factory, and it is possible for 3rd parties to register custom socket connection
+ * types for specific combination of socket family/type/protocol using
+ * g_socket_connection_factory_register_type().
+ *
+ * Since: 2.22
+ **/
+
 G_DEFINE_TYPE (GSocketConnection,
 	       g_socket_connection, G_TYPE_IO_STREAM);
 
@@ -293,6 +310,21 @@ connection_factory_equal (gconstpointer _a,
 static GHashTable *connection_factories = NULL;
 G_LOCK_DEFINE_STATIC(connection_factories);
 
+/**
+ * g_socket_connection_factory_register_type:
+ * @g_type: a #GType, inheriting from G_SOCKET_CONNECTION
+ * @family: a #GSocketFamily.
+ * @type: a #GSocketType
+ * @protocol: a protocol id
+ *
+ * Looks up the #GType to be used when creating socket connections on
+ * sockets with the specified @family,@type and @protocol_id.
+ *
+ * If no type is registered, the #GSocketConnection base type is returned.
+ *
+ * Returns: a #GType
+ * Since: 2.22
+ **/
 void
 g_socket_connection_factory_register_type (GType g_type,
 					   GSocketFamily family,
@@ -301,6 +333,8 @@ g_socket_connection_factory_register_type (GType g_type,
 {
   ConnectionFactory *factory;
 
+  g_return_if_fail (g_type_is_a (g_type, G_TYPE_SOCKET_CONNECTION));
+
   G_LOCK (connection_factories);
 
   if (connection_factories == NULL)
@@ -331,6 +365,20 @@ init_builtin_types (void)
   a_type = g_tcp_connection_get_type ();
 }
 
+/**
+ * g_socket_connection_factory_lookup_type:
+ * @family: a #GSocketFamily.
+ * @type: a #GSocketType
+ * @protocol_id: a protocol id
+ *
+ * Looks up the #GType to be used when creating socket connections on
+ * sockets with the specified @family,@type and @protocol_id.
+ *
+ * If no type is registered, the #GSocketConnection base type is returned.
+ *
+ * Returns: a #GType
+ * Since: 2.22
+ **/
 GType
 g_socket_connection_factory_lookup_type (GSocketFamily family,
 					 GSocketType type,
@@ -361,6 +409,17 @@ g_socket_connection_factory_lookup_type (GSocketFamily family,
   return g_type;
 }
 
+/**
+ * g_socket_connection_factory_create_connection:
+ * @socket: a #GSocket.
+ *
+ * Creates a #GSocketConnection subclass of the right type for
+ * @socket.
+ *
+ * Returns: a #GSocketConnection
+ *
+ * Since: 2.22
+ **/
 GSocketConnection *
 g_socket_connection_factory_create_connection (GSocket *socket)
 {
diff --git a/gio/gsocketconnection.h b/gio/gsocketconnection.h
index ecbcccd..a3c3809 100644
--- a/gio/gsocketconnection.h
+++ b/gio/gsocketconnection.h
@@ -1,4 +1,4 @@
-/*
+/* GIO - GLib Input, Output and Streaming Library
  * Copyright © 2008 Christian Kellner, Samuel Cormier-Iijima
  * Copyright © 2009 Codethink Limited
  *
@@ -7,19 +7,28 @@
  * by the Free Software Foundation; either version 2 of the licence or (at
  * your option) any later version.
  *
- * See the included COPYING file for more information.
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General
+ * Public License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
+ * Boston, MA 02111-1307, USA.
  *
  * Authors: Christian Kellner <gicmo gnome org>
  *          Samuel Cormier-Iijima <sciyoshi gmail com>
  *          Ryan Lortie <desrt desrt ca>
+ *          Alexander Larsson <alexl redhat com>
  */
 
 #if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
 #error "Only <gio/gio.h> can be included directly."
 #endif
 
-#ifndef _gsocketconnection_h_
-#define _gsocketconnection_h_
+#ifndef __G_SOCKET_CONNECTION_H__
+#define __G_SOCKET_CONNECTION_H__
 
 #include <glib-object.h>
 #include <gio/gsocket.h>
@@ -39,9 +48,16 @@ G_BEGIN_DECLS
 #define G_SOCKET_CONNECTION_GET_CLASS(inst)                 (G_TYPE_INSTANCE_GET_CLASS ((inst),                      \
                                                              G_TYPE_SOCKET_CONNECTION, GSocketConnectionClass))
 
+/**
+ * GSocketConnection:
+ *
+ * A socket connection GIOStream object for connection-oriented sockets.
+ *
+ * Since: 2.22
+ **/
+typedef struct _GSocketConnection                           GSocketConnection;
 typedef struct _GSocketConnectionPrivate                    GSocketConnectionPrivate;
 typedef struct _GSocketConnectionClass                      GSocketConnectionClass;
-typedef struct _GSocketConnection                           GSocketConnection;
 
 struct _GSocketConnectionClass
 {
@@ -69,4 +85,4 @@ GSocketConnection *g_socket_connection_factory_create_connection (GSocket
 
 G_END_DECLS
 
-#endif /* _gsocketconnection_h_ */
+#endif /* __G_SOCKET_CONNECTION_H__ */