add/fix gtk-doc comments, make functions match prototypes, etc

	* libsoup/*.[ch]: add/fix gtk-doc comments, make functions match
	prototypes, etc

	* docs/reference/*: update, fix, etc

1 files changed, 34 insertions, 7 deletions

diff --git a/libsoup/soup-socket.h b/libsoup/soup-socket.h
index bb43caa7..5db21741 100644
--- a/libsoup/soup-socket.h
+++ b/libsoup/soup-socket.h
@@ -38,6 +38,31 @@ typedef struct {
 #define SOUP_SOCKET_IS_SERVER        "is-server"
 #define SOUP_SOCKET_SSL_CREDENTIALS  "ssl-creds"
 
+/**
+ * SoupSocketCallback:
+ * @sock: the #SoupSocket
+ * @status: an HTTP status code indicating success or failure
+ * @user_data: the data passed to soup_socket_client_new_async()
+ *
+ * The callback function passed to soup_socket_client_new_async().
+ **/
+typedef void (*SoupSocketCallback)            (SoupSocket         *sock,
+					       guint               status,
+					       gpointer            user_data);
+
+/**
+ * SoupSocketListenerCallback:
+ * @listener: the listening #SoupSocket
+ * @sock: the newly-received #SoupSocket
+ * @user_data: the data passed to soup_socket_server_new().
+ *
+ * The callback function passed to soup_socket_server_new(), which
+ * receives new connections.
+ **/
+typedef void (*SoupSocketListenerCallback)    (SoupSocket         *listener,
+					       SoupSocket         *sock,
+					       gpointer            user_data);
+
 GType soup_socket_get_type (void);
 
 SoupSocket    *soup_socket_new                (const char         *optname1,
@@ -54,13 +79,6 @@ gboolean       soup_socket_start_proxy_ssl    (SoupSocket         *sock,
 void           soup_socket_disconnect         (SoupSocket         *sock);
 gboolean       soup_socket_is_connected       (SoupSocket         *sock);
 
-typedef void (*SoupSocketCallback)            (SoupSocket         *sock,
-					       guint               status,
-					       gpointer            user_data);
-typedef void (*SoupSocketListenerCallback)    (SoupSocket         *listener,
-					       SoupSocket         *sock,
-					       gpointer            user_data);
-
 SoupSocket    *soup_socket_client_new_async   (const char         *hostname,
 					       guint               port,
 					       gpointer            ssl_creds,
@@ -79,6 +97,15 @@ SoupAddress   *soup_socket_get_local_address  (SoupSocket         *sock);
 SoupAddress   *soup_socket_get_remote_address (SoupSocket         *sock);
 
 
+/**
+ * SoupSocketIOStatus:
+ * @SOUP_SOCKET_OK: Success
+ * @SOUP_SOCKET_WOULD_BLOCK: Cannot read/write any more at this time
+ * @SOUP_SOCKET_EOF: End of file
+ * @SOUP_SOCKET_ERROR: Other error
+ *
+ * Return value from the #SoupSocket IO methods.
+ **/
 typedef enum {
 	SOUP_SOCKET_OK,
 	SOUP_SOCKET_WOULD_BLOCK,