[gnio] Add API docs for GSocket

[Alexander Larsson <alexl src gnome org>]

commit 0bbe445979987289dd128be84f7eaa6e84ca2297
Author: Alexander Larsson <alexl redhat com>
Date:   Thu May 7 16:38:40 2009 +0200

    Add API docs for GSocket
---
 gio/gsocket.c |  617 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 gio/gsocket.h |   57 ++++++-
 2 files changed, 650 insertions(+), 24 deletions(-)

diff --git a/gio/gsocket.c b/gio/gsocket.c
index 3be1072..7fc9e4b 100644
--- a/gio/gsocket.c
+++ b/gio/gsocket.c
@@ -49,6 +49,55 @@
 #include "gnioenums.h"
 #include <gio/gioerror.h>
 
+/**
+ * SECTION:gsocket
+ * @short_description: Lowlevel network socket handling
+ * @include: gio/gio.h
+ * @see_also: #GInitable
+ *
+ * A #GSocket is a lowlevel networking primitive. It is a more or less
+ * direct mapping of the BSD socket API in a portable GObject based API.
+ * It support both the unix socket implementations and winsock2 on Windows.
+ *
+ * #GSocket is the platform independent base upon which the higher level
+ * network primitives are based. Applications are not typically meant to
+ * use it directly, but rather through classes like #GSocketClient, etc.
+ * However there may be cases where direct use of #GSocket is useful.
+ *
+ * TODO: Add more references to the highlevel API once that is more
+ * finalized.
+ *
+ * #GSocket implements the #GInitable interface, so if it is manually constucted
+ * by e.g. g_object_new() you must call g_initable_init() and check the
+ * results before using the object. This is done automatically in
+ * g_socket_new() and g_socket_new_from_fd(), so these functions can return
+ * %NULL.
+ *
+ * Sockets operate in two general modes, blocking or non-blocking. When
+ * in blocking modes all operations block until the requested operation
+ * is finished or there is an error. In non-blocking mode all calls that
+ * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
+ * To know when a call would successfully run you can call g_socket_condition_check(),
+ * or g_socket_condition_wait(). You can also use g_socket_create_source() and
+ * attach it to a #GMainContext to get callbacks when I/O is possible.
+ *
+ * Applications should always be able to handle getting a %G_IO_ERROR_WOULD_BLOCK
+ * error even when some other function said that I/O was possible. This can
+ * easily happen in case of a race condition in the application, but it can
+ * also happen for other reasons. For instance, on Windows a socket is
+ * always seen as writable until a write returns %G_IO_ERROR_WOULD_BLOCK.
+ *
+ * #GSocket<!-- -->s can be both connection oriented or datagram based.
+ * For connection oriented types you must first establish a connection by
+ * either connecting to an address or accepting a connection from another
+ * address. For connectionless socket types the target/source address is
+ * specified or recieved in each I/O operation.
+ *
+ * All socket file descriptors are set to be close-on-exec.
+ *
+ * Since: 2.22
+ **/
+
 static void     g_socket_initable_iface_init (GInitableIface  *iface);
 static gboolean g_socket_initable_init       (GInitable       *initable,
 					      GCancellable    *cancellable,
@@ -741,7 +790,22 @@ g_socket_initable_init (GInitable *initable,
   return TRUE;
 }
 
-
+/**
+ * g_socket_new:
+ * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.
+ * @type: the socket type to use.
+ * @protocol: the name of the protocol to use, or %NULL.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Creates a new #GSocket with the defined family, type and protocol.
+ * If @protocol is %NULL the default protocol type for the family and
+ * type is used.
+ *
+ * Returns: a #GSocket or %NULL on error.
+ *     Free the returned object with g_object_unref().
+ *
+ * Since: 2.22
+ **/
 GSocket *
 g_socket_new (GSocketFamily family,
 	      GSocketType type,
@@ -756,6 +820,24 @@ g_socket_new (GSocketFamily family,
 				   NULL));
 }
 
+/**
+ * g_socket_new_from_fd:
+ * @fd: a native socket file descriptor.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Creates a new #GSocket from a native file descriptor
+ * or winsock SOCKET handle.
+ *
+ * This reads all the settings from the file descriptor so that
+ * all properties should work. However, on Windows it is not possible
+ * to read the non-blocking property of a socket so it won't be
+ * reliably detected.
+ *
+ * Returns: a #GSocket or %NULL on error.
+ *     Free the returned object with g_object_unref().
+ *
+ * Since: 2.22
+ **/
 GSocket *
 g_socket_new_from_fd (gint fd,
 		      GError **error)
@@ -766,6 +848,27 @@ g_socket_new_from_fd (gint fd,
 				   NULL));
 }
 
+/**
+ * g_socket_set_blocking:
+ * @socket: a #GSocket.
+ * @blocking: Whether to use blocking I/O or not.
+ *
+ * Sets the blocking mode of the socket. In blocking mode
+ * all operations block until they succeed or there is an error. In
+ * non-blocking mode all functions return results immediately or
+ * with a %G_IO_ERROR_WOULD_BLOCK error.
+ *
+ * All sockets are created in blocking mode. Although on windows any
+ * call to g_socket_create_source(), g_socket_condition_check(), or
+ * g_socket_condition_wait() will automatically enable non-blocking mode.
+ *
+ * This call generally always succeeds, however on Windows you cannot
+ * set a socket to blocking while there is a source from g_socket_create_source()
+ * for @socket alive. If you need to ensure blocking mode was enabled, read the
+ * current value with g_socket_get_blocking() after setting.
+ *
+ * Since: 2.22
+ **/
 void
 g_socket_set_blocking (GSocket  *socket,
                        gboolean  blocking)
@@ -810,6 +913,17 @@ g_socket_set_blocking (GSocket  *socket,
   g_object_notify (G_OBJECT (socket), "blocking");
 }
 
+/**
+ * g_socket_get_blocking:
+ * @socket: a #GSocket.
+ *
+ * Gets the blocking mode of the socket. For details on blocking I/O,
+ * see g_socket_set_blocking().
+ *
+ * Returns: %TRUE if blocking I/O is used, %FALSE otherwise.
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_get_blocking (GSocket *socket)
 {
@@ -818,6 +932,31 @@ g_socket_get_blocking (GSocket *socket)
   return socket->priv->blocking;
 }
 
+/**
+ * g_socket_set_reuse_address:
+ * @socket: a #GSocket.
+ * @reuse: Whether to use allow address reuse or not.
+ *
+ * Setting @reuse to %TRUE enables reusing the socket
+ * address used by a previous socket when binding to
+ * an address with g_socket_bind().
+ *
+ * The exact behaviour of this call varies a bit. For TCP sockets on Unix
+ * it means that we allow reuse of a socket address that was previously in
+ * use and still have outstanding connections in the WAIT state. Enabling
+ * this for a server socket is generally safe and useful, as it means you
+ * can quickly restart a server application without waiting for all the
+ * old connections to time out.
+ *
+ * However, on windows it means that all reuse of the address is allowed,
+ * even if there is another actively listening socket bound to that port.
+ * This is not generally a good thing to use. However, on Windows you
+ * are automatically allowed to bind to an address if there are outstanding
+ * connections in the WAIT state, so address reuse is not as important
+ * there as on Unix.
+ *
+ * Since: 2.22
+ **/
 void
 g_socket_set_reuse_address (GSocket  *socket,
                             gboolean  reuse)
@@ -843,6 +982,17 @@ g_socket_set_reuse_address (GSocket  *socket,
   g_object_notify (G_OBJECT (socket), "reuse_address");
 }
 
+/**
+ * g_socket_get_reuse_address:
+ * @socket: a #GSocket.
+ *
+ * Gets the reuse_addres mode of the socket. For details on this,
+ * see g_socket_set_reuse_address().
+ *
+ * Returns: %TRUE if address reuse is used, %FALSE otherwise.
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_get_reuse_address (GSocket *socket)
 {
@@ -851,6 +1001,26 @@ g_socket_get_reuse_address (GSocket *socket)
   return socket->priv->reuse_address;
 }
 
+/**
+ * g_socket_set_keepalive:
+ * @socket: a #GSocket.
+ * @keepalive: Whether to use try to keep the connection alive or not.
+ *
+ * Setting @reuse to %TRUE enables the sending of periodic ping requests
+ * on idle connections in order to keep the conenction alive. This is only
+ * useful for connection oriented sockets. The exact period used between
+ * each ping is system and protocol dependent.
+ *
+ * Sending keepalive requests like this has a few disadvantages. For instance,
+ * it uses more network bandwidth, and it makes your application more sensitive
+ * to temporary outages in the network (i.e. if a cable is pulled your otherwise
+ * idle connection could be terminated, whereas otherwise it would survive unless
+ * actually used before the cable was reinserted). However, it is sometimes
+ * useful to ensure that connections are eventually terminated if e.g. the
+ * remote side is disconnected, so as to avoid leaking resources forever.
+ *
+ * Since: 2.22
+ **/
 void
 g_socket_set_keepalive (GSocket *socket,
 			gboolean keepalive)
@@ -876,6 +1046,17 @@ g_socket_set_keepalive (GSocket *socket,
   g_object_notify (G_OBJECT (socket), "keepalive");
 }
 
+/**
+ * g_socket_get_keepalive:
+ * @socket: a #GSocket.
+ *
+ * Gets the keepalive mode of the socket. For details on this,
+ * see g_socket_set_keepalive().
+ *
+ * Returns: %TRUE if keepalive is active, %FALSE otherwise.
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_get_keepalive (GSocket *socket)
 {
@@ -884,6 +1065,17 @@ g_socket_get_keepalive (GSocket *socket)
   return socket->priv->keepalive;
 }
 
+/**
+ * g_socket_get_listen_backlog:
+ * @socket: a #GSocket.
+ *
+ * Gets the listen backlog setting of the socket. For details on this,
+ * see g_socket_set_listen_backlog().
+ *
+ * Returns: the maximum number of pending connections.
+ *
+ * Since: 2.22
+ **/
 gint
 g_socket_get_listen_backlog  (GSocket                 *socket)
 {
@@ -892,6 +1084,18 @@ g_socket_get_listen_backlog  (GSocket                 *socket)
   return socket->priv->listen_backlog;
 }
 
+/**
+ * g_socket_set_listen_backlog:
+ * @socket: a #GSocket.
+ * @backlog: the maximum number of pending connections.
+ *
+ * Sets the maximum number of outstanding connections allowed
+ * when listening on this socket. If more clients than this are
+ * connecting to the socket and the application is not handling them
+ * on time then the new connections will be refused.
+ *
+ * Since: 2.22
+ **/
 void
 g_socket_set_listen_backlog (GSocket *socket,
 			     gint backlog)
@@ -905,6 +1109,20 @@ g_socket_set_listen_backlog (GSocket *socket,
     }
 }
 
+/**
+ * g_socket_get_fd:
+ * @socket: a #GSocket.
+ *
+ * Returns the underlying OS socket object. On unix this
+ * is a socket file descriptor, and on windows this is
+ * a Winsock2 SOCKET handle. This may be useful for
+ * doing platform specific or otherwise unusual operations
+ * on the socket.
+ *
+ * Returns: the file descriptor of the socket.
+ *
+ * Since: 2.22
+ **/
 int
 g_socket_get_fd (GSocket *socket)
 {
@@ -913,6 +1131,18 @@ g_socket_get_fd (GSocket *socket)
   return socket->priv->fd;
 }
 
+/**
+ * g_socket_get_local_address:
+ * @socket: a #GSocket.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Try to get the local address of a bound socket. This is only
+ * useful if the socket has been bound to a local address.
+ *
+ * Returns: a #GSocketAddress or %NULL on error.
+ *
+ * Since: 2.22
+ **/
 GSocketAddress *
 g_socket_get_local_address (GSocket  *socket,
                             GError  **error)
@@ -937,6 +1167,18 @@ g_socket_get_local_address (GSocket  *socket,
   return socket->priv->local_address;
 }
 
+/**
+ * g_socket_get_remote_address:
+ * @socket: a #GSocket.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Try to get the remove address of a connected socket. This is only
+ * useful for connection oriented sockets that have been connected.
+ *
+ * Returns: a #GSocketAddress or %NULL on error.
+ *
+ * Since: 2.22
+ **/
 GSocketAddress *
 g_socket_get_remote_address (GSocket  *socket,
                              GError  **error)
@@ -961,6 +1203,17 @@ g_socket_get_remote_address (GSocket  *socket,
   return socket->priv->remote_address;
 }
 
+/**
+ * g_socket_is_connected:
+ * @socket: a #GSocket.
+ *
+ * Check whether the socket is connected. This is only useful for
+ * connection-oriented sockets.
+ *
+ * Returns: %TRUE if socket is connected, %FALSE otherwise.
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_is_connected (GSocket *socket)
 {
@@ -969,6 +1222,21 @@ g_socket_is_connected (GSocket *socket)
   return socket->priv->remote_address != NULL;
 }
 
+/**
+ * g_socket_listen:
+ * @socket: a #GSocket.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Marks the socket as a server socket, i.e. a socket that is used
+ * to accept incomming requests using g_socket_accept().
+ *
+ * Before calling this the socket must be bound to a local address using
+ * g_socket_bind().
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_listen (GSocket  *socket,
                  GError  **error)
@@ -990,6 +1258,23 @@ g_socket_listen (GSocket  *socket,
   return TRUE;
 }
 
+/**
+ * g_socket_bind:
+ * @socket: a #GSocket.
+ * @address: a #GSocketAddress specifying the local address.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * When a socket is created it is attached to an address family, but it
+ * doesn't have an address in this family. g_socket_bind() assigns the
+ * address (sometimes called name) of the socket.
+ *
+ * It is generally required to bind to a local address before you can
+ * recieve connections. (See g_socket_listen() and g_socket_accept() ).
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_bind (GSocket         *socket,
                GSocketAddress  *address,
@@ -1022,6 +1307,27 @@ g_socket_bind (GSocket         *socket,
   }
 }
 
+/**
+ * g_socket_accept:
+ * @socket: a #GSocket.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Accept incomming connections on a connection-based socket. This removes
+ * the first outstanding connection request from the listening socket and
+ * creates a #GSocket object for it.
+ *
+ * The @socket must be bound to a local address with g_socket_bind() and
+ * must be listening for incomming connections (g_socket_listen()).
+ *
+ * If there are no outstanding conneoctions then the operation will block
+ * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
+ * To be notified of an incomming connection, wait for the %G_IO_IN condition.
+ *
+ * Returns: a new #GSocket, or %NULL on error.
+ *     Free the returned object with g_object_unref().
+ *
+ * Since: 2.22
+ **/
 GSocket *
 g_socket_accept (GSocket       *socket,
                  GError       **error)
@@ -1109,6 +1415,32 @@ g_socket_accept (GSocket       *socket,
   return new_socket;
 }
 
+/**
+ * g_socket_connect:
+ * @socket: a #GSocket.
+ * @address: a #GSocketAddress specifying the remote address.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Connect the socket to the specified remote address.
+ *
+ * For connection oriented socket this generally means we attempt to make
+ * a connection to the @address. For a connection-less socket it sets
+ * the default address for g_socket_send() and discards all incomming datagrams
+ * from other sources.
+ *
+ * Generally connection oriented sockets can only connect once, but connection-less
+ * sockets can connect multiple times to change the default address.
+ *
+ * If the connect call needs to do network I/O it will block, unless
+ * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
+ * and the user can be notified of the connectiong finishing by waiting
+ * for the G_IO_OUT condition. The result of the connection can then be
+ * checked with g_socket_get_pending_error().
+ *
+ * Returns: %TRUE if connected, %FALSE on error.
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_connect (GSocket         *socket,
                   GSocketAddress  *address,
@@ -1157,6 +1489,32 @@ g_socket_connect (GSocket         *socket,
   return TRUE;
 }
 
+/**
+ * g_socket_receive:
+ * @socket: a #GSocket
+ * @buffer: a buffer to read data into (which should be at least count bytes long).
+ * @size: the number of bytes that will be read from the stream
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Receive data (up to @size bytes) from a socket. This is mainly used by
+ * connection oriented sockets, it is identical to g_socket_receive_from()
+ * with @address set to %NULL.
+ *
+ * If a message is too long to fit in @buffer, excess bytes may be discarded
+ * depending on the type of socket the message is received from.
+ *
+ * If the socket is in blocking mode the call will block until there is
+ * some data to recieve or there is an error. If there is no data availible
+ * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
+ * will be returned. To be notified of availible data, wait for the %G_IO_IN
+ * condition.
+ *
+ * On error -1 is returned and @error is set accordingly.
+ *
+ * Return value: Number of bytes read, or -1 on error
+ *
+ * Since: 2.22
+ **/
 gssize
 g_socket_receive (GSocket       *socket,
                   gchar         *buffer,
@@ -1195,9 +1553,35 @@ g_socket_receive (GSocket       *socket,
   return ret;
 }
 
+/**
+ * g_socket_receive_from:
+ * @socket: a #GSocket
+ * @address: a pointer to a #GSocketAddress pointer, or %NULL
+ * @buffer: a buffer to read data into (which should be at least count bytes long).
+ * @size: the number of bytes that will be read from the stream
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Receive data (up to @size bytes) from a socket.
+ *
+ * If @address is non-%NULL then @address will be set equal to the
+ * source address of the received packet.
+ * @address is owned by the caller.
+ *
+ * If the socket is in blocking mode the call will block until there is
+ * some data to recieve or there is an error. If there is no data availible
+ * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
+ * will be returned. To be notified of availible data, wait for the %G_IO_IN
+ * condition.
+ *
+ * On error -1 is returned and @error is set accordingly.
+ *
+ * Return value: Number of bytes read, or -1 on error
+ *
+ * Since: 2.22
+ **/
 gssize
 g_socket_receive_from (GSocket       *socket,
-		       GSocketAddress         **address,
+		       GSocketAddress  **address,
 		       gchar         *buffer,
 		       gsize          size,
 		       GError       **error)
@@ -1214,6 +1598,34 @@ g_socket_receive_from (GSocket       *socket,
 				   error);
 }
 
+/**
+ * g_socket_send:
+ * @socket: a #GSocket
+ * @buffer: the buffer containing the data to send.
+ * @size: the number of bytes to send
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Tries to send @size bytes from @buffer on the socket. This is mainly used by
+ * connection oriented sockets, it is identical to g_socket_send_to()
+ * with @address set to %NULL.
+ *
+ * If the socket is in blocking mode the call will block until there is
+ * space for the data in the socket queue. If there is no space availible
+ * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
+ * will be returned. To be notified of availible spave, wait for the %G_IO_OUT
+ * condition.
+ *
+ * Note that on Windows you can't rely on a %G_IO_OUT condition
+ * not producing a %G_IO_ERROR_WOULD_BLOCK error, as this is how Winsock
+ * write notification works. However, robust apps should always be able to
+ * handle this since it can easily appear in other cases too.
+ *
+ * On error -1 is returned and @error is set accordingly.
+ *
+ * Return value: Number of bytes read, or -1 on error
+ *
+ * Since: 2.22
+ **/
 gssize
 g_socket_send (GSocket      *socket,
                const gchar  *buffer,
@@ -1252,6 +1664,35 @@ g_socket_send (GSocket      *socket,
   return ret;
 }
 
+/**
+ * g_socket_send_to:
+ * @socket: a #GSocket
+ * @address: a #GSocketAddress, or %NULL
+ * @buffer: the buffer containing the data to send.
+ * @size: the number of bytes to send
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Tries to send @size bytes from @buffer to @address. If @address is
+ * %NULL then the message is sent to the default reciever (set by
+ * g_socket_connect()).
+ *
+ * If the socket is in blocking mode the call will block until there is
+ * space for the data in the socket queue. If there is no space availible
+ * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
+ * will be returned. To be notified of availible spave, wait for the %G_IO_OUT
+ * condition.
+ *
+ * Note that on Windows you can't rely on a %G_IO_OUT condition
+ * not producing a %G_IO_ERROR_WOULD_BLOCK error, as this is how Winsock
+ * write notification works. However, robust apps should always be able to
+ * handle this since it can easily appear in other cases too.
+ *
+ * On error -1 is returned and @error is set accordingly.
+ *
+ * Return value: Number of bytes read, or -1 on error
+ *
+ * Since: 2.22
+ **/
 gssize
 g_socket_send_to (GSocket      *socket,
 		  GSocketAddress *address,
@@ -1271,6 +1712,28 @@ g_socket_send_to (GSocket      *socket,
 				0, error);
 }
 
+/**
+ * g_socket_close:
+ * @socket: a #GSocket
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Closes the socket, shutting down any active connection.
+ *
+ * Closing a socket does not wait for all outstanding I/O operations to finish,
+ * so the caller should not rely on them to be guaranteed to complete even
+ * if the close returns with no error.
+ *
+ * Once the socket is closed, all other operations will return %G_IO_ERROR_CLOSED.
+ * Closing a stream multiple times will not return an error.
+ *
+ * Sockets will be automatically closed when the last reference
+ * is dropped, but you might want to call this function to make sure
+ * resources are released as early as possible.
+ *
+ * Return value: %TRUE on success, %FALSE on error
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_close (GSocket *socket,
 		GError **error)
@@ -1303,6 +1766,7 @@ g_socket_close (GSocket *socket,
 		       socket_io_error_from_errno (errsv),
 		       _("Error closing socket: %s"),
 		       socket_strerror (errsv));
+	  return FALSE;
 	}
       break;
     }
@@ -1317,9 +1781,19 @@ g_socket_close (GSocket *socket,
 
   socket->priv->closed = TRUE;
 
-  return res != -1;
+  return TRUE;
 }
 
+/**
+ * g_socket_is_closed:
+ * @socket: a #GSocket
+ *
+ * Checks whether a socket is closed.
+ *
+ * Return value: %TRUE if socket is closed, %FALSE otherwise
+ *
+ * Since: 2.22
+ **/
 gboolean
 g_socket_is_closed (GSocket *socket)
 {
@@ -1342,7 +1816,7 @@ broken_check    (GSource  *source)
 }
 
 static gboolean
-broken_dispatch (GSource    *source, 
+broken_dispatch (GSource    *source,
 		 GSourceFunc callback,
 		 gpointer    user_data)
 {
@@ -1626,6 +2100,28 @@ winsock_source_new (GSocket      *socket,
 }
 #endif
 
+/**
+ * g_socket_create_source:
+ * @socket: a #GSocket
+ * @condition: a #GIOCondition mask to monitor
+ * @cancellable: a %GCancellable or %NULL
+ *
+ * Creates a %GSource that can be attached to a %GMainContext to monitor
+ * for the availiblilty of the specified @condition on the socket.
+ *
+ * The callback on the source is of the #GSocketSourceFunc type.
+ *
+ * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
+ * these conditions will always be reported output if they are true.
+ *
+ * @cancellable if not %NULL can be used to cancel the source, which will
+ * cause the source to trigger, reporting the current condition. You can
+ * check for this in the callback using g_cancellable_is_cancelled().
+ *
+ * Return value: a newly allocated %GSource, free with g_source_unref().
+ *
+ * Since: 2.22
+ **/
 GSource *
 g_socket_create_source (GSocket      *socket,
                         GIOCondition  condition,
@@ -1646,7 +2142,6 @@ g_socket_create_source (GSocket      *socket,
  * g_socket_condition_check:
  * @socket: a #GSocket
  * @condition: a #GIOCondition mask to check
- * @returns: the @GIOCondition mask of the current state
  *
  * Checks on the readiness of @socket to perform operations.  The
  * operations specified in @condition are checked for and masked
@@ -1657,6 +2152,10 @@ g_socket_create_source (GSocket      *socket,
  * these conditions will always be set in the output if they are true.
  *
  * This call never blocks.
+ *
+ * Return value: the @GIOCondition mask of the current state
+ *
+ * Since: 2.22
  **/
 GIOCondition
 g_socket_condition_check (GSocket       *socket,
@@ -1698,13 +2197,16 @@ g_socket_condition_check (GSocket       *socket,
  * @condition: a #GIOCondition mask to wait for
  * @cancellable: a #GCancellable, or %NULL
  * @error: a #GError pointer, or %NULL
- * @returns: %TRUE if the condition was met, else %FALSE
  *
  * Waits for @condition to become true on @socket.  When the condition
  * becomes true, %TRUE is returned.
  *
  * If @cancellable is cancelled before the condition becomes true then
- * %FALSE is returned and @error, if non-%NULL, is set.
+ * %FALSE is returned and @error, if non-%NULL, is set to %G_IO_ERROR_CANCELLED.
+ *
+ * Return value: %TRUE if the condition was met, %FALSE otherwise
+ *
+ * Since: 2.22
  **/
 gboolean
 g_socket_condition_wait (GSocket       *socket,
@@ -1791,6 +2293,60 @@ g_socket_condition_wait (GSocket       *socket,
   #endif
 }
 
+/**
+ * g_socket_send_to:
+ * @socket: a #GSocket
+ * @address: a #GSocketAddress, or %NULL
+ * @vectors: an array of #GOutputVector structs
+ * @num_vectors: the number of elements in @vectors, or -1
+ * @messages: a pointer to an array of #GSocketControlMessages, or
+ *   %NULL.
+ * @num_messages: number of elements in @messages, or -1.
+ * @flags: an int containing #GSocketMsgFlags flags
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Send data to @address on @socket.  This is the most complicated and
+ * fully-featured version of this call. For easier use, see
+ * g_socket_send() and g_socket_send_to().
+ *
+ * If @address is %NULL then the message is sent to the default reciever
+ * (set by g_socket_connect()).
+ *
+ * @vector must point to an array of #GOutputVector structs and
+ * @num_vectors must be the length of this array.  These structs
+ * describe the buffers that the sent data will be gathered from.
+ * If @num_vector is -1, then @vector is assumed to be terminated
+ * by a #GOutputVector with a %NULL buffer pointer.
+ *
+ *
+ * @messages, if non-%NULL, is taken to point to an array of @num_messages 
+ * #GSocketControlMessage instances. These correspond to the control
+ * messages to be sent on the socket.
+ * If @num_messages is -1 then @messages is treated as a %NULL-terminated
+ * array.
+ *
+ * @flags modify how the message sent. The commonly availible arguments
+ * for this is availible in the #GSocketMsgFlags enum, but the
+ * values there are the same as the system values, and the flags
+ * are passed in as-is, so you can pass in system specific flags too.
+ *
+ * If the socket is in blocking mode the call will block until there is
+ * space for the data in the socket queue. If there is no space availible
+ * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
+ * will be returned. To be notified of availible spave, wait for the %G_IO_OUT
+ * condition.
+ *
+ * Note that on Windows you can't rely on a %G_IO_OUT condition
+ * not producing a %G_IO_ERROR_WOULD_BLOCK error, as this is how Winsock
+ * write notification works. However, robust apps should always be able to
+ * handle this since it can easily appear in other cases too.
+ *
+ * On error -1 is returned and @error is set accordingly.
+ *
+ * Return value: Number of bytes read, or -1 on error
+ *
+ * Since: 2.22
+ **/
 gssize
 g_socket_send_message (GSocket                *socket,
                        GSocketAddress         *address,
@@ -1994,27 +2550,29 @@ g_socket_send_message (GSocket                *socket,
 /**
  * g_socket_receive_message:
  * @socket: a #GSocket
- * @address: a pointer to the source address, or %NULL
+ * @address: a pointer to a #GSocketAddress pointer, or %NULL
  * @vectors: an array of #GInputVector structs
- * @num_vectors: the number of elements in @vectors
- * @messages: a pointer to an array of #GSocketControlMessages, or
- * %NULL
- * @num_messages: a pointer to the number of elements in @messages, or
- * %NULL
- * @flags: a pointer to flags XXX enum this
+ * @num_vectors: the number of elements in @vectors, or -1
+ * @messages: a pointer which will be filled with an array of
+ *     #GSocketControlMessages, or %NULL
+ * @num_messages: a pointer which will be filled with the number of
+ *    elements in @messages, or %NULL
+ * @flags: a pointer to an int containing #GSocketMsgFlags flags
  * @error: a #GError pointer, or %NULL
- * @returns: the number of bytes received, or -1 on error
  *
  * Receive data from a socket.  This is the most complicated and
- * fully-featured version of this call.
+ * fully-featured version of this call. For easier use, see
+ * g_socket_receive() and g_socket_receive_from().
  *
- * If @address is non-%NULL and @socket is unconnected then @address
- * will be set equal to the source address of the received packet.
+ * If @address is non-%NULL then @address will be set equal to the
+ * source address of the received packet.
  * @address is owned by the caller.
  *
  * @vector must point to an array of #GInputVector structs and
  * @num_vectors must be the length of this array.  These structs
- * describe the buffers that received data will be skattered into.
+ * describe the buffers that received data will be scattered into.
+ * If @num_vector is -1, then @vector is assumed to be terminated
+ * by a #GInputVector with a %NULL buffer pointer.
  *
  * As a special case, if the size of the array is zero (in which case,
  * @vectors may of course be %NULL), then a single byte is received
@@ -2026,7 +2584,8 @@ g_socket_send_message (GSocket                *socket,
  * be set to point to a newly-allocated array of
  * #GSocketControlMessage instances.  These correspond to the control
  * messages received from the kernel, one #GSocketControlMessage per
- * message from the kernel.  This array is NULL-terminated.
+ * message from the kernel.  This array is %NULL-terminated and must be
+ * freed by the caller using g_free().
  *
  * @num_messages, if non-%NULL, will be set to the number of control
  * messages received.
@@ -2035,10 +2594,22 @@ g_socket_send_message (GSocket                *socket,
  * @num_messages gives the number of #GSocketControlMessage instances
  * in @messages (ie: not including the %NULL terminator).
  *
- * @flags is an in/out parameter.  This will be improved. XXX
+ * @flags is an in/out parameter. The commonly availible arguments
+ * for this is availible in the #GSocketMsgFlags enum, but the
+ * values there are the same as the system values, and the flags
+ * are passed in as-is, so you can pass in system specific flags too.
+ *
+ * If the socket is in blocking mode the call will block until there is
+ * some data to recieve or there is an error. If there is no data availible
+ * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
+ * will be returned. To be notified of availible data, wait for the %G_IO_IN
+ * condition.
+ *
+ * On error -1 is returned and @error is set accordingly.
+ *
+ * Return value: Number of bytes read, or -1 on error
  *
- * In the case of any error, -1 will be returned and @error, if
- * non-%NULL, will be set.
+ * Since: 2.22
  **/
 gssize
 g_socket_receive_message (GSocket                 *socket,
diff --git a/gio/gsocket.h b/gio/gsocket.h
index c604b37..3e7c70a 100644
--- a/gio/gsocket.h
+++ b/gio/gsocket.h
@@ -51,12 +51,30 @@ struct _GSocketClass
   GObjectClass parent_class;
 };
 
+/**
+ * GSocket:
+ *
+ * A lowlevel network socket object.
+ *
+ * Since: 2.22
+ **/
 struct _GSocket
 {
   GObject parent_instance;
   GSocketPrivate *priv;
 };
 
+/**
+ * GSocketType:
+ * @G_SOCKET_TYPE_INVALID: Type unknown or wrong
+ * @G_SOCKET_TYPE_STREAM: Reliable connection-based byte streams (e.g. TCP).
+ * @G_SOCKET_TYPE_DATAGRAM: Connectionless, unreliable datagram passing. (e.g. UDP) 
+ * @G_SOCKET_TYPE_SEQPACKET: Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP).
+ *
+ * Flags used when creating a #GSocket. Some protocols may not implement all the socket types.
+ *
+ * Since: 2.22
+ */
 typedef enum
 {
   G_SOCKET_TYPE_INVALID,
@@ -65,6 +83,19 @@ typedef enum
   G_SOCKET_TYPE_SEQPACKET,
 } GSocketType;
 
+/**
+ * GSocketMsgFlags:
+ * @G_SOCKET_MSG_OOB: Request to send/recieve out of band data.
+ * @G_SOCKET_MSG_PEEK: Read data from the socket without removing it from the queue.
+ * @G_SOCKET_MSG_DONTROUTE: Don't use a gateway to send out the packet, only send to hosts on directly connected networks.
+ *
+ * Flags used in g_socket_receive_message() and g_socket_send_message(). The flags listed in the enum are
+ * some commonly availible flags, but the values used for them are the same as on the platform, and any other
+ * flags are passed in/out as is. So to use a platform specific flag, just include the right system header and
+ * pass in the flag.
+ *
+ * Since: 2.22
+ */
 typedef enum
 {
   G_SOCKET_MSG_INVALID,
@@ -73,19 +104,43 @@ typedef enum
   G_SOCKET_MSG_DONTROUTE = GLIB_SYSDEF_MSG_DONTROUTE
 } GSocketMsgFlags;
 
+/**
+ * GInputVector:
+ *
+ * Structure used for scatter/gather data input.
+ *
+ * Since: 2.22
+ */
 typedef struct
 {
   gpointer buffer;
   gsize size;
 } GInputVector;
 
+/**
+ * GOutputVector:
+ *
+ * Structure used for scatter/gather data output.
+ *
+ * Since: 2.22
+ */
 typedef struct
 {
   gconstpointer buffer;
   gsize size;
 } GOutputVector;
 
-typedef gboolean (*GSocketSourceFunc) (gpointer     user_data,
+/**
+ * GSocketSourceFunc:
+ * @user_data: data passed in by the user.
+ * @condition: the current condition at the source fired.
+ *
+ * This is the function type of the callback used for the #GSource
+ * returned by g_socket_create_source().
+ *
+ * Since: 2.22
+ */
+typedef gboolean (*GSocketSourceFunc) (gpointer user_data,
 				       GIOCondition condition);
 
 GType                  g_socket_get_type                (void);