add/fix lots of gtk-doc comments

	* libsoup/*: add/fix lots of gtk-doc comments

	* libsoup/soup-misc.c (soup_str_case_hash, soup_str_case_equal):
	Fix bug noticed while documenting. (We were using the
	locale-case-insensitive functions rather than the g_ascii_ ones.)

	* libsoup/soup-message.h (SoupMessageFlags): remove the (never
	implemented) NO_PIPELINE and NO_COOKIE flags.

	* docs/reference/tmpl/*.sgml: Regenerate, fill in some stuff.
	There are still problems here with gtk-doc not recognizing many of
	the objects in libsoup...

38 files changed, 948 insertions, 242 deletions

diff --git a/ChangeLog b/ChangeLog
index 3fe2d48b..28f19786 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2004-08-26  Dan Winship  <danw@novell.com>
+
+	* libsoup/*: add/fix lots of gtk-doc comments
+	
+	* libsoup/soup-misc.c (soup_str_case_hash, soup_str_case_equal):
+	Fix bug noticed while documenting. (We were using the
+	locale-case-insensitive functions rather than the g_ascii_ ones.)
+
+	* libsoup/soup-message.h (SoupMessageFlags): remove the (never
+	implemented) NO_PIPELINE and NO_COOKIE flags.
+
+	* docs/reference/tmpl/*.sgml: Regenerate, fill in some stuff.
+	There are still problems here with gtk-doc not recognizing many of
+	the objects in libsoup...
+
 2004-08-13  JP Rosevear  <jpr@novell.com>
 
 	* configure.in: bump version, libtool number
diff --git a/docs/reference/libsoup-sections.txt b/docs/reference/libsoup-sections.txt
index 3abb9186..e382c954 100644
--- a/docs/reference/libsoup-sections.txt
+++ b/docs/reference/libsoup-sections.txt
@@ -11,7 +11,6 @@ soup_message_new
 soup_message_new_from_uri
 soup_message_set_request
 soup_message_set_response
-soup_message_cancel
 soup_message_add_header
 soup_message_get_header
 soup_message_get_header_list
@@ -206,8 +205,6 @@ SOUP_SESSION_MAX_CONNS
 SOUP_SESSION_MAX_CONNS_PER_HOST
 SOUP_SESSION_USE_NTLM
 SOUP_SESSION_SSL_CA_FILE
-soup_session_new
-soup_session_new_with_options
 soup_session_queue_message
 soup_session_requeue_message
 soup_session_send_message
diff --git a/docs/reference/tmpl/libsoup-unused.sgml b/docs/reference/tmpl/libsoup-unused.sgml
index 4d49f3c6..ab933b6e 100644
--- a/docs/reference/tmpl/libsoup-unused.sgml
+++ b/docs/reference/tmpl/libsoup-unused.sgml
@@ -89,6 +89,12 @@ soup
 @i: 
 @parent: 
 
+<!-- ##### STRUCT SoupAddress ##### -->
+<para>
+
+</para>
+
+
 <!-- ##### STRUCT SoupSoapMessagePrivate ##### -->
 <para>
 
@@ -157,6 +163,13 @@ soup
 @msg: 
 @req: 
 
+<!-- ##### FUNCTION soup_message_cleanup ##### -->
+<para>
+
+</para>
+
+@req: 
+
 <!-- ##### FUNCTION soup_message_io_cancel ##### -->
 <para>
 
diff --git a/docs/reference/tmpl/soup-address.sgml b/docs/reference/tmpl/soup-address.sgml
index b4f7b8a5..edc69448 100644
--- a/docs/reference/tmpl/soup-address.sgml
+++ b/docs/reference/tmpl/soup-address.sgml
@@ -2,11 +2,18 @@
 SoupAddress
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Higher-level IP address object
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+#SoupAddress represents the address of a TCP connection endpoint; both
+the IP address and the port. (It is somewhat like an object-oriented
+version of struct #sockaddr.)
+</para>
 
+<para>
+If libsoup was built with IPv6 support, #SoupAddress will allow both
+IPv4 and IPv6 addresses.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,15 +23,19 @@ SoupAddress
 
 <!-- ##### ENUM SoupAddressFamily ##### -->
 <para>
-
+The supported address families. Note that the
+%SOUP_ADDRESS_FAMILY_IPV6 constant is available even if libsoup was
+built without IPv6 support, but attempting to create an IPv6 address
+will fail in that case.
 </para>
 
-@SOUP_ADDRESS_FAMILY_IPV4: 
-@SOUP_ADDRESS_FAMILY_IPV6: 
+@SOUP_ADDRESS_FAMILY_IPV4: an IPv4 address
+@SOUP_ADDRESS_FAMILY_IPV6: an IPv6 address
 
 <!-- ##### MACRO SOUP_ADDRESS_ANY_PORT ##### -->
 <para>
-
+This can be passed to any #SoupAddress method that expects a port to
+indicate that you don't care what port is used.
 </para>
 
 
@@ -61,12 +72,12 @@ SoupAddress
 
 <!-- ##### USER_FUNCTION SoupAddressCallback ##### -->
 <para>
-
+The callback function passed to soup_address_resolve_async().
 </para>
 
-@addr: 
-@status: 
-@data: 
+@addr: the #SoupAddress that was resolved
+@status: %SOUP_STATUS_OK or %SOUP_STATUS_CANT_RESOLVE
+@data: the user data that was passed to soup_address_resolve_async()
 
 
 <!-- ##### FUNCTION soup_address_resolve_async ##### -->
@@ -77,9 +88,6 @@ SoupAddress
 @addr: 
 @callback: 
 @user_data: 
-<!-- # Unused Parameters # -->
-@cb: 
-@data: 
 
 
 <!-- ##### FUNCTION soup_address_resolve_sync ##### -->
diff --git a/docs/reference/tmpl/soup-auth-basic.sgml b/docs/reference/tmpl/soup-auth-basic.sgml
index 7dc91b10..5beb539e 100644
--- a/docs/reference/tmpl/soup-auth-basic.sgml
+++ b/docs/reference/tmpl/soup-auth-basic.sgml
@@ -2,11 +2,12 @@
 SoupAuthBasic
 
 <!-- ##### SECTION Short_Description ##### -->
-
+HTTP Basic Authentication
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+This implements the Basic HTTP Authentication mechanism, as described
+in RFC 2617.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/reference/tmpl/soup-auth-digest.sgml b/docs/reference/tmpl/soup-auth-digest.sgml
index 16cf820d..af0f0c1b 100644
--- a/docs/reference/tmpl/soup-auth-digest.sgml
+++ b/docs/reference/tmpl/soup-auth-digest.sgml
@@ -2,11 +2,12 @@
 SoupAuthDigest
 
 <!-- ##### SECTION Short_Description ##### -->
-
+HTTP Digest Authentication
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+This implements the Digest HTTP Authentication mechanism, as described
+in RFC 2617.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/reference/tmpl/soup-auth.sgml b/docs/reference/tmpl/soup-auth.sgml
index 7283fe59..5fb0bd95 100644
--- a/docs/reference/tmpl/soup-auth.sgml
+++ b/docs/reference/tmpl/soup-auth.sgml
@@ -2,16 +2,25 @@
 SoupAuth
 
 <!-- ##### SECTION Short_Description ##### -->
-
+HTTP Authentication support
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+#SoupAuth objects store the authentication data associated with a
+given bit of webspace. They are created and maintained automatically
+by #SoupSession.
+</para>
 
+<para>
+#SoupAuth itself is an abstract class. Specific HTTP Authentication
+mechanisms are implemented by its subclasses. (NTLM authentication,
+which works quite differently from normal HTTP authentication, is
+handled by #SoupConnectionNTLM.)
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+SoupAuthBasic, SoupAuthDigest, SoupSession, SoupConnectionNTLM
 </para>
 
 <!-- ##### STRUCT SoupAuth ##### -->
diff --git a/docs/reference/tmpl/soup-connection.sgml b/docs/reference/tmpl/soup-connection.sgml
index 7c3b6eb9..9cb5e6c0 100644
--- a/docs/reference/tmpl/soup-connection.sgml
+++ b/docs/reference/tmpl/soup-connection.sgml
@@ -47,12 +47,12 @@ SoupConnection
 
 <!-- ##### USER_FUNCTION SoupConnectionCallback ##### -->
 <para>
-
+The callback function passed to soup_connection_connect_async().
 </para>
 
-@sock: 
-@status: 
-@data: 
+@conn: the #SoupConnection
+@status: an HTTP status code indicating success or failure
+@data: the data passed to soup_connection_connect_async()
 
 
 <!-- ##### FUNCTION soup_connection_connect_async ##### -->
diff --git a/docs/reference/tmpl/soup-dns.sgml b/docs/reference/tmpl/soup-dns.sgml
index b98bc007..8bef2e9c 100644
--- a/docs/reference/tmpl/soup-dns.sgml
+++ b/docs/reference/tmpl/soup-dns.sgml
@@ -2,7 +2,7 @@
 soup-dns
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Low-level DNS routines
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
diff --git a/docs/reference/tmpl/soup-message-private.sgml b/docs/reference/tmpl/soup-message-private.sgml
index 04e16f8f..581531f2 100644
--- a/docs/reference/tmpl/soup-message-private.sgml
+++ b/docs/reference/tmpl/soup-message-private.sgml
@@ -23,14 +23,6 @@ soup-message-private
 @phase: 
 
 
-<!-- ##### FUNCTION soup_message_cleanup ##### -->
-<para>
-
-</para>
-
-@req: 
-
-
 <!-- ##### FUNCTION soup_message_cleanup_response ##### -->
 <para>
 
diff --git a/docs/reference/tmpl/soup-message-queue.sgml b/docs/reference/tmpl/soup-message-queue.sgml
index efc18ce6..0abe8736 100644
--- a/docs/reference/tmpl/soup-message-queue.sgml
+++ b/docs/reference/tmpl/soup-message-queue.sgml
@@ -16,7 +16,8 @@ soup-message-queue
 
 <!-- ##### STRUCT SoupMessageQueueIter ##### -->
 <para>
-
+An opaque data structure used to iterate the elements of a
+#SoupMessageQueue.
 </para>
 
 
diff --git a/docs/reference/tmpl/soup-message.sgml b/docs/reference/tmpl/soup-message.sgml
index 32357ecf..97706bdb 100644
--- a/docs/reference/tmpl/soup-message.sgml
+++ b/docs/reference/tmpl/soup-message.sgml
@@ -16,57 +16,68 @@ SoupMessage
 
 <!-- ##### ENUM SoupMessageStatus ##### -->
 <para>
-
+Enum indicating the lifecycle of a #SoupMessage.
 </para>
 
-@SOUP_MESSAGE_STATUS_IDLE: 
-@SOUP_MESSAGE_STATUS_QUEUED: 
-@SOUP_MESSAGE_STATUS_CONNECTING: 
-@SOUP_MESSAGE_STATUS_RUNNING: 
-@SOUP_MESSAGE_STATUS_FINISHED: 
+@SOUP_MESSAGE_STATUS_IDLE: The message has not yet been queued.
+@SOUP_MESSAGE_STATUS_QUEUED: The message has been queued, but is
+waiting for a connection to be available.
+@SOUP_MESSAGE_STATUS_CONNECTING: The message is waiting for a specific
+connection to finish connecting.
+@SOUP_MESSAGE_STATUS_RUNNING: The message is being processed.
+@SOUP_MESSAGE_STATUS_FINISHED: The message is complete (request and
+response both processed).
 
 <!-- ##### MACRO SOUP_MESSAGE_IS_STARTING ##### -->
-<para>
 
+<para>
+Tests if @msg is in a "starting" state, waiting to be sent. (More
+commonly used to test if a message has been requeued after its first
+attempt.)
 </para>
 
-@msg: 
+@msg: a #SoupMessage
+@Returns: %TRUE if @msg is waiting to be sent.
 
 
 <!-- ##### ENUM SoupTransferEncoding ##### -->
 <para>
-
+How the length of a request or response is to be encoded.
 </para>
 
-@SOUP_TRANSFER_UNKNOWN: 
-@SOUP_TRANSFER_CHUNKED: 
-@SOUP_TRANSFER_CONTENT_LENGTH: 
+@SOUP_TRANSFER_UNKNOWN: HTTP 1.0-style (content ends when the
+connection is closed)
+@SOUP_TRANSFER_CHUNKED: chunked encoding (only supported for response)
+@SOUP_TRANSFER_CONTENT_LENGTH: Content-Length
 
 <!-- ##### ENUM SoupOwnership ##### -->
 <para>
-
+Used by #SoupDataBuffer (and several functions) to indicate the
+ownership of a buffer.
 </para>
 
-@SOUP_BUFFER_SYSTEM_OWNED: 
-@SOUP_BUFFER_USER_OWNED: 
-@SOUP_BUFFER_STATIC: 
+@SOUP_BUFFER_SYSTEM_OWNED: The data is owned by soup and it can free
+it when it is done with it.
+@SOUP_BUFFER_USER_OWNED: The data is owned by the user, who is
+responsible for freeing it at the right point
+@SOUP_BUFFER_STATIC: The data should not be freed.
 
 <!-- ##### STRUCT SoupDataBuffer ##### -->
 <para>
-
+A data buffer used in several places.
 </para>
 
-@owner: 
-@body: 
-@length: 
+@owner: the ownership of the data
+@body: the data itself
+@length: length of @body
 
 <!-- ##### USER_FUNCTION SoupMessageCallbackFn ##### -->
 <para>
-
+A callback function used by many #SoupMessage methods.
 </para>
 
-@req: 
-@user_data: 
+@req: the #SoupMessage in question
+@user_data: user data
 
 
 <!-- ##### FUNCTION soup_message_new ##### -->
@@ -178,11 +189,11 @@ SoupMessage
 
 <!-- ##### ENUM SoupHttpVersion ##### -->
 <para>
-
+Indicates the HTTP protocol version being used.
 </para>
 
-@SOUP_HTTP_1_0: 
-@SOUP_HTTP_1_1: 
+@SOUP_HTTP_1_0: HTTP 1.0 (RFC 1945)
+@SOUP_HTTP_1_1: HTTP 1.1 (RFC 2616)
 
 <!-- ##### FUNCTION soup_message_set_http_version ##### -->
 <para>
@@ -231,14 +242,19 @@ SoupMessage
 
 <!-- ##### ENUM SoupMessageFlags ##### -->
 <para>
-
+Various flags that can be set on a #SoupMessage to alter its behavior.
 </para>
 
-@SOUP_MESSAGE_NO_PIPELINE: 
-@SOUP_MESSAGE_NO_REDIRECT: 
-@SOUP_MESSAGE_NO_COOKIE: 
-@SOUP_MESSAGE_OVERWRITE_CHUNKS: 
-@SOUP_MESSAGE_EXPECT_CONTINUE: 
+@SOUP_MESSAGE_NO_REDIRECT: The session should not follow redirect
+(3xx) responses received by this message.
+@SOUP_MESSAGE_OVERWRITE_CHUNKS: Rather than building up the response
+body in %response, each new chunk should overwrite the previous one.
+(This can be used if you are connecting to the %got_chunk signal or
+have installed a %SOUP_MESSAGE_BODY_CHUNK handler.)
+@SOUP_MESSAGE_EXPECT_CONTINUE: This will cause an "Expect:
+100-continue" header to be added to the outgoing request, giving the
+server the opportunity to reject the message (eg, with a 401
+Unauthorized) before the full request body is sent.
 
 <!-- ##### FUNCTION soup_message_set_flags ##### -->
 <para>
@@ -260,13 +276,18 @@ SoupMessage
 
 <!-- ##### ENUM SoupHandlerPhase ##### -->
 <para>
-
+Indicates when a handler added with soup_message_add_handler() or the
+like will be run.
 </para>
 
-@SOUP_HANDLER_POST_REQUEST: 
-@SOUP_HANDLER_PRE_BODY: 
-@SOUP_HANDLER_BODY_CHUNK: 
-@SOUP_HANDLER_POST_BODY: 
+@SOUP_HANDLER_POST_REQUEST: The handler should run immediately after
+sending the request body
+@SOUP_HANDLER_PRE_BODY: The handler should run before reading the
+response body (after reading the headers).
+@SOUP_HANDLER_BODY_CHUNK: The handler should run after every body
+chunk is read. (See also %SOUP_MESSAGE_OVERWRITE_CHUNKS.)
+@SOUP_HANDLER_POST_BODY: The handler should run after the entire
+message body has been read.
 
 <!-- ##### FUNCTION soup_message_add_handler ##### -->
 <para>
diff --git a/docs/reference/tmpl/soup-method.sgml b/docs/reference/tmpl/soup-method.sgml
index f4c39d8a..e6c6bb3d 100644
--- a/docs/reference/tmpl/soup-method.sgml
+++ b/docs/reference/tmpl/soup-method.sgml
@@ -2,11 +2,14 @@
 soup-method
 
 <!-- ##### SECTION Short_Description ##### -->
-
+HTTP method-related defines.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+These can be used if you don't want to specify the HTTP method to
+soup_message_new() as an explicit string. This is purely a stylistic
+consideration. There is no difference between using the define and
+the string itself.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -128,7 +131,9 @@ soup-method
 
 <!-- ##### ENUM SoupMethodId ##### -->
 <para>
-
+This enumeration is used internally by routines that need to check the
+HTTP method in a #SoupMessage against several different possibilities,
+to avoid repeated strcmp()s.
 </para>
 
 @SOUP_METHOD_ID_UNKNOWN: 
diff --git a/docs/reference/tmpl/soup-socket.sgml b/docs/reference/tmpl/soup-socket.sgml
index e5716dbe..8a6389a9 100644
--- a/docs/reference/tmpl/soup-socket.sgml
+++ b/docs/reference/tmpl/soup-socket.sgml
@@ -109,22 +109,25 @@ SoupSocket
 
 <!-- ##### USER_FUNCTION SoupSocketCallback ##### -->
 <para>
-
+The callback function passed to soup_socket_client_new_async().
 </para>
 
-@sock: 
-@status: 
+@sock: the #SoupSocket
+@status: an HTTP status code indicating success or failure
 @user_data: 
+<!-- # Unused Parameters # -->
+@data: the data passed to soup_socket_client_new_async()
 
 
 <!-- ##### USER_FUNCTION SoupSocketListenerCallback ##### -->
 <para>
-
+The callback function passed to soup_socket_server_new(), which
+receives new connections.
 </para>
 
-@listener: 
-@sock: 
-@user_data: 
+@listener: the listening #SoupSocket
+@sock: the newly-received #SoupSocket
+@user_data: the data passed to soup_socket_server_new().
 
 
 <!-- ##### FUNCTION soup_socket_client_new_async ##### -->
@@ -188,13 +191,13 @@ SoupSocket
 
 <!-- ##### ENUM SoupSocketIOStatus ##### -->
 <para>
-
+Return value from the #SoupSocket IO methods.
 </para>
 
-@SOUP_SOCKET_OK: 
-@SOUP_SOCKET_WOULD_BLOCK: 
-@SOUP_SOCKET_EOF: 
-@SOUP_SOCKET_ERROR: 
+@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
 
 <!-- ##### FUNCTION soup_socket_read ##### -->
 <para>
diff --git a/docs/reference/tmpl/soup-ssl.sgml b/docs/reference/tmpl/soup-ssl.sgml
index e2e9b9a2..c8cedf79 100644
--- a/docs/reference/tmpl/soup-ssl.sgml
+++ b/docs/reference/tmpl/soup-ssl.sgml
@@ -16,11 +16,11 @@ soup-ssl
 
 <!-- ##### ENUM SoupSSLType ##### -->
 <para>
-
+What kind of SSL connection this is.
 </para>
 
-@SOUP_SSL_TYPE_CLIENT: 
-@SOUP_SSL_TYPE_SERVER: 
+@SOUP_SSL_TYPE_CLIENT: the client side of an SSL connection
+@SOUP_SSL_TYPE_SERVER: the server side of an SSL connection
 
 <!-- ##### FUNCTION soup_ssl_get_client_credentials ##### -->
 <para>
diff --git a/docs/reference/tmpl/soup-status.sgml b/docs/reference/tmpl/soup-status.sgml
index 4d45ea45..374a820b 100644
--- a/docs/reference/tmpl/soup-status.sgml
+++ b/docs/reference/tmpl/soup-status.sgml
@@ -2,7 +2,7 @@
 soup-status
 
 <!-- ##### SECTION Short_Description ##### -->
-
+HTTP and Soup status codes
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -16,122 +16,136 @@ soup-status
 
 <!-- ##### ENUM SoupStatusClass ##### -->
 <para>
-
+The classes of HTTP and Soup status codes
 </para>
 
-@SOUP_STATUS_CLASS_TRANSPORT_ERROR: 
-@SOUP_STATUS_CLASS_INFORMATIONAL: 
-@SOUP_STATUS_CLASS_SUCCESS: 
-@SOUP_STATUS_CLASS_REDIRECT: 
-@SOUP_STATUS_CLASS_CLIENT_ERROR: 
-@SOUP_STATUS_CLASS_SERVER_ERROR: 
+@SOUP_STATUS_CLASS_TRANSPORT_ERROR: Network or Soup-level error
+@SOUP_STATUS_CLASS_INFORMATIONAL: HTTP 1xx response providing partial
+information about the state of a request
+@SOUP_STATUS_CLASS_SUCCESS: HTTP 2xx successful response
+@SOUP_STATUS_CLASS_REDIRECT: HTTP 3xx redirection response
+@SOUP_STATUS_CLASS_CLIENT_ERROR: HTTP 4xx client error response
+@SOUP_STATUS_CLASS_SERVER_ERROR: HTTP 5xx server error response
 
 <!-- ##### MACRO SOUP_STATUS_IS_INFORMATIONAL ##### -->
 <para>
-
+Tests if @status is an Informational (1xx) response.
 </para>
 
-@x: 
+@status: an HTTP status code
+@Returns: %TRUE if @status is an Information (1xx) response.
 
 
 <!-- ##### MACRO SOUP_STATUS_IS_SUCCESSFUL ##### -->
 <para>
-
+Tests if @status is a Successful (2xx) response.
 </para>
 
-@x: 
+@status: an HTTP status code
+@Returns: %TRUE if @status is a Successful (2xx) response.
 
 
 <!-- ##### MACRO SOUP_STATUS_IS_REDIRECTION ##### -->
 <para>
-
+Tests if @status is a Redirection (3xx) response.
 </para>
 
-@x: 
+@status: an HTTP status code
+@Returns: %TRUE if @status is a Redirection (3xx) response.
 
 
 <!-- ##### MACRO SOUP_STATUS_IS_CLIENT_ERROR ##### -->
 <para>
-
+Tests if @status is a Client Error (4xx) response.
 </para>
 
-@x: 
+@status: an HTTP status code
+@Returns: %TRUE if @status is a Client Error (4xx) response.
 
 
 <!-- ##### MACRO SOUP_STATUS_IS_SERVER_ERROR ##### -->
 <para>
-
+Tests if @status is a Server Error (5xx) response.
 </para>
 
-@x: 
+@status: an HTTP status code
+@Returns: %TRUE if @status is a Server Error (5xx) response.
 
 
 <!-- ##### ENUM SoupKnownStatusCode ##### -->
 <para>
-
+These represent the known HTTP status code values, plus various
+network and internal errors.
 </para>
 
-@SOUP_STATUS_NONE: 
-@SOUP_STATUS_CANCELLED: 
-@SOUP_STATUS_CANT_RESOLVE: 
-@SOUP_STATUS_CANT_RESOLVE_PROXY: 
-@SOUP_STATUS_CANT_CONNECT: 
-@SOUP_STATUS_CANT_CONNECT_PROXY: 
-@SOUP_STATUS_SSL_FAILED: 
-@SOUP_STATUS_IO_ERROR: 
-@SOUP_STATUS_MALFORMED: 
-@SOUP_STATUS_TRY_AGAIN: 
-@SOUP_STATUS_CONTINUE: 
-@SOUP_STATUS_SWITCHING_PROTOCOLS: 
-@SOUP_STATUS_PROCESSING: 
-@SOUP_STATUS_OK: 
-@SOUP_STATUS_CREATED: 
-@SOUP_STATUS_ACCEPTED: 
-@SOUP_STATUS_NON_AUTHORITATIVE: 
-@SOUP_STATUS_NO_CONTENT: 
-@SOUP_STATUS_RESET_CONTENT: 
-@SOUP_STATUS_PARTIAL_CONTENT: 
-@SOUP_STATUS_MULTI_STATUS: 
-@SOUP_STATUS_MULTIPLE_CHOICES: 
-@SOUP_STATUS_MOVED_PERMANENTLY: 
-@SOUP_STATUS_FOUND: 
-@SOUP_STATUS_MOVED_TEMPORARILY: 
-@SOUP_STATUS_SEE_OTHER: 
-@SOUP_STATUS_NOT_MODIFIED: 
-@SOUP_STATUS_USE_PROXY: 
-@SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL: 
-@SOUP_STATUS_TEMPORARY_REDIRECT: 
-@SOUP_STATUS_BAD_REQUEST: 
-@SOUP_STATUS_UNAUTHORIZED: 
-@SOUP_STATUS_PAYMENT_REQUIRED: 
-@SOUP_STATUS_FORBIDDEN: 
-@SOUP_STATUS_NOT_FOUND: 
-@SOUP_STATUS_METHOD_NOT_ALLOWED: 
-@SOUP_STATUS_NOT_ACCEPTABLE: 
-@SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED: 
-@SOUP_STATUS_PROXY_UNAUTHORIZED: 
-@SOUP_STATUS_REQUEST_TIMEOUT: 
-@SOUP_STATUS_CONFLICT: 
-@SOUP_STATUS_GONE: 
-@SOUP_STATUS_LENGTH_REQUIRED: 
-@SOUP_STATUS_PRECONDITION_FAILED: 
-@SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE: 
-@SOUP_STATUS_REQUEST_URI_TOO_LONG: 
-@SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE: 
-@SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: 
-@SOUP_STATUS_INVALID_RANGE: 
-@SOUP_STATUS_EXPECTATION_FAILED: 
-@SOUP_STATUS_UNPROCESSABLE_ENTITY: 
-@SOUP_STATUS_LOCKED: 
-@SOUP_STATUS_FAILED_DEPENDENCY: 
-@SOUP_STATUS_INTERNAL_SERVER_ERROR: 
-@SOUP_STATUS_NOT_IMPLEMENTED: 
-@SOUP_STATUS_BAD_GATEWAY: 
-@SOUP_STATUS_SERVICE_UNAVAILABLE: 
-@SOUP_STATUS_GATEWAY_TIMEOUT: 
-@SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED: 
-@SOUP_STATUS_INSUFFICIENT_STORAGE: 
-@SOUP_STATUS_NOT_EXTENDED: 
+@SOUP_STATUS_NONE: No status available. (Eg, the message has not been
+sent yet)
+@SOUP_STATUS_CANCELLED: Message was cancelled locally
+@SOUP_STATUS_CANT_RESOLVE: Unable to resolve destination host name
+@SOUP_STATUS_CANT_RESOLVE_PROXY: Unable to resolve proxy host name
+@SOUP_STATUS_CANT_CONNECT: Unable to connect to remote host
+@SOUP_STATUS_CANT_CONNECT_PROXY: Unable to connect to proxy
+@SOUP_STATUS_SSL_FAILED: SSL negotiation failed
+@SOUP_STATUS_IO_ERROR: A network error occurred, or the other end
+closed the connection unexpectedly
+@SOUP_STATUS_MALFORMED: Malformed data (usually a programmer error)
+@SOUP_STATUS_TRY_AGAIN: Try again. (Only returned in certain
+specifically documented cases)
+@SOUP_STATUS_CONTINUE: 100 Continue (HTTP)
+@SOUP_STATUS_SWITCHING_PROTOCOLS: 101 Switching Protocols (HTTP)
+@SOUP_STATUS_PROCESSING: 102 Processing (WebDAV)
+@SOUP_STATUS_OK: 200 Success (HTTP). Also used by many lower-level
+soup routines to indicate success.
+@SOUP_STATUS_CREATED: 201 Created (HTTP)
+@SOUP_STATUS_ACCEPTED: 202 Accepted (HTTP)
+@SOUP_STATUS_NON_AUTHORITATIVE: 203 Non-Authoritative Information (HTTP)
+@SOUP_STATUS_NO_CONTENT: 204 No Content (HTTP)
+@SOUP_STATUS_RESET_CONTENT: 205 Reset Content (HTTP)
+@SOUP_STATUS_PARTIAL_CONTENT: 206 Partial Content (HTTP)
+@SOUP_STATUS_MULTI_STATUS: 207 Multi-Status (WebDAV)
+@SOUP_STATUS_MULTIPLE_CHOICES: 300 Multiple Choices (HTTP)
+@SOUP_STATUS_MOVED_PERMANENTLY: 301 Moved Permanently (HTTP)
+@SOUP_STATUS_FOUND: 302 Found (HTTP)
+@SOUP_STATUS_MOVED_TEMPORARILY: 302 Moved Temporarily (old name, RFC 2068)
+@SOUP_STATUS_SEE_OTHER: 303 See Other (HTTP)
+@SOUP_STATUS_NOT_MODIFIED: 304 Not Modified (HTTP)
+@SOUP_STATUS_USE_PROXY: 305 Use Proxy (HTTP)
+@SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL: 306 [Unused] (HTTP)
+@SOUP_STATUS_TEMPORARY_REDIRECT: 307 Temporary Redirect (HTTP)
+@SOUP_STATUS_BAD_REQUEST: 400 Bad Request (HTTP)
+@SOUP_STATUS_UNAUTHORIZED: 401 Unauthorized (HTTP)
+@SOUP_STATUS_PAYMENT_REQUIRED: 402 Payment Required (HTTP)
+@SOUP_STATUS_FORBIDDEN: 403 Forbidden (HTTP)
+@SOUP_STATUS_NOT_FOUND: 404 Not Found (HTTP)
+@SOUP_STATUS_METHOD_NOT_ALLOWED: 405 Method Not Allowed (HTTP)
+@SOUP_STATUS_NOT_ACCEPTABLE: 406 Not Acceptable (HTTP)
+@SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED: 407 Proxy Authentication
+Required (HTTP)
+@SOUP_STATUS_PROXY_UNAUTHORIZED: shorter alias for %SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED
+@SOUP_STATUS_REQUEST_TIMEOUT: 408 Request Timeout (HTTP)
+@SOUP_STATUS_CONFLICT: 409 Conflict (HTTP)
+@SOUP_STATUS_GONE: 410 Gone (HTTP)
+@SOUP_STATUS_LENGTH_REQUIRED: 411 Length Required (HTTP)
+@SOUP_STATUS_PRECONDITION_FAILED: 412 Precondition Failed (HTTP)
+@SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE: 413 Request Entity Too Large (HTTP)
+@SOUP_STATUS_REQUEST_URI_TOO_LONG: 414 Request-URI Too Long (HTTP)
+@SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE: 415 Unsupported Media Type (HTTP)
+@SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: 416 Requested Range Not
+Satisfiable (HTTP)
+@SOUP_STATUS_INVALID_RANGE: shorter alias for %SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE
+@SOUP_STATUS_EXPECTATION_FAILED: 417 Expectation Failed (HTTP)
+@SOUP_STATUS_UNPROCESSABLE_ENTITY: 422 Unprocessable Entity (WebDAV)
+@SOUP_STATUS_LOCKED: 423 Locked (WebDAV)
+@SOUP_STATUS_FAILED_DEPENDENCY: 424 Failed Dependency (WebDAV)
+@SOUP_STATUS_INTERNAL_SERVER_ERROR: 500 Internal Server Error (HTTP)
+@SOUP_STATUS_NOT_IMPLEMENTED: 501 Not Implemented (HTTP)
+@SOUP_STATUS_BAD_GATEWAY: 502 Bad Gateway (HTTP)
+@SOUP_STATUS_SERVICE_UNAVAILABLE: 503 Service Unavailable (HTTP)
+@SOUP_STATUS_GATEWAY_TIMEOUT: 504 Gateway Timeout (HTTP)
+@SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED: 505 HTTP Version Not
+Supported (HTTP)
+@SOUP_STATUS_INSUFFICIENT_STORAGE: 507 Insufficient Storage (WebDAV)
+@SOUP_STATUS_NOT_EXTENDED: 510 Not Extended (RFC 2774)
 
 <!-- ##### FUNCTION soup_status_get_phrase ##### -->
 <para>
diff --git a/docs/reference/tmpl/soup-uri.sgml b/docs/reference/tmpl/soup-uri.sgml
index c344f580..5058ce64 100644
--- a/docs/reference/tmpl/soup-uri.sgml
+++ b/docs/reference/tmpl/soup-uri.sgml
@@ -16,20 +16,21 @@ soup-uri
 
 <!-- ##### TYPEDEF SoupProtocol ##### -->
 <para>
-
+#GQuark is used for SoupProtocol so that the protocol of a #SoupUri
+can be tested quickly.
 </para>
 
 
 <!-- ##### MACRO SOUP_PROTOCOL_HTTP ##### -->
 <para>
-
+This returns the #SoupProtocol value for "http".
 </para>
 
 
 
 <!-- ##### MACRO SOUP_PROTOCOL_HTTPS ##### -->
 <para>
-
+This returns the #SoupProtocol value for "https".
 </para>
 
 
diff --git a/libsoup/soup-address.c b/libsoup/soup-address.c
index 4450fb22..c4d42ac0 100644
--- a/libsoup/soup-address.c
+++ b/libsoup/soup-address.c
@@ -200,8 +200,10 @@ soup_address_new (const char *name, guint port)
  * @sa: a pointer to a sockaddr
  * @len: size of @sa
  *
- * Return value: a #SoupAddress equivalent to @sa (or %NULL if @sa's
+ * Returns a #SoupAddress equivalent to @sa (or %NULL if @sa's
  * address family isn't supported)
+ *
+ * Return value: the new #SoupAddress
  **/
 SoupAddress *
 soup_address_new_from_sockaddr (struct sockaddr *sa, int len)
@@ -221,11 +223,13 @@ soup_address_new_from_sockaddr (struct sockaddr *sa, int len)
 /**
  * soup_address_new_any:
  * @family: the address family
- * @port: the port number (usually 0, meaning "any port")
+ * @port: the port number (usually %SOUP_ADDRESS_ANY_PORT)
  *
- * Return value: a #SoupAddress corresponding to the "any" address
+ * Returns a #SoupAddress corresponding to the "any" address
  * for @family (or %NULL if @family isn't supported), suitable for
  * passing to soup_socket_server_new().
+ *
+ * Return value: the new #SoupAddress
  **/
 SoupAddress *
 soup_address_new_any (SoupAddressFamily family, guint port)
@@ -250,8 +254,9 @@ soup_address_new_any (SoupAddressFamily family, guint port)
  * soup_address_get_name:
  * @addr: a #SoupAddress
  *
- * Return value: the hostname associated with @addr, or %NULL if
- * it is not known.
+ * Returns the hostname associated with @addr.
+ *
+ * Return value: the hostname, or %NULL if it is not known.
  **/
 const char *
 soup_address_get_name (SoupAddress *addr)
@@ -312,7 +317,9 @@ soup_address_get_physical (SoupAddress *addr)
  * soup_address_get_port:
  * @addr: a #SoupAddress
  *
- * Return value: the port associated with @addr
+ * Returns the port associated with @addr.
+ *
+ * Return value: the port
  **/
 guint
 soup_address_get_port (SoupAddress *addr)
diff --git a/libsoup/soup-auth.c b/libsoup/soup-auth.c
index 245c4a64..ba80a2f5 100644
--- a/libsoup/soup-auth.c
+++ b/libsoup/soup-auth.c
@@ -39,6 +39,17 @@ static AuthScheme known_auth_schemes [] = {
 	{ NULL }
 };
 
+/* FIXME: it should be possible to register new auth schemes! */
+
+/**
+ * soup_auth_new_from_header_list:
+ * @vals: a list of WWW-Authenticate headers from a server response
+ *
+ * Creates a #SoupAuth value based on the strongest available
+ * supported auth type in @vals.
+ *
+ * Return value: the new #SoupAuth, or %NULL if none could be created.
+ **/
 SoupAuth *
 soup_auth_new_from_header_list (const GSList *vals)
 {
@@ -78,6 +89,16 @@ soup_auth_new_from_header_list (const GSList *vals)
 	return auth;
 }
 
+/**
+ * soup_auth_authenticate:
+ * @auth: a #SoupAuth
+ * @username: the username provided by the user or client
+ * @password: the password provided by the user or client
+ *
+ * This is called by the session after requesting a username and
+ * password from the application. @auth should take the information
+ * and do whatever scheme-specific processing is needed.
+ **/
 void
 soup_auth_authenticate (SoupAuth *auth, const char *username, const char *password)
 {
@@ -88,6 +109,14 @@ soup_auth_authenticate (SoupAuth *auth, const char *username, const char *passwo
 	SOUP_AUTH_GET_CLASS (auth)->authenticate (auth, username, password);
 }
 
+/**
+ * soup_auth_get_scheme_name:
+ * @auth: a #SoupAuth
+ *
+ * Returns @auth's scheme name. (Eg, "Basic")
+ *
+ * Return value: the scheme name
+ **/
 const char *
 soup_auth_get_scheme_name (SoupAuth *auth)
 {
@@ -96,6 +125,14 @@ soup_auth_get_scheme_name (SoupAuth *auth)
 	return SOUP_AUTH_GET_CLASS (auth)->scheme_name;
 }
 
+/**
+ * soup_auth_get_realm:
+ * @auth: a #SoupAuth
+ *
+ * Returns @auth's realm, if any.
+ *
+ * Return value: the realm name
+ **/
 const char *
 soup_auth_get_realm (SoupAuth *auth)
 {
@@ -104,6 +141,14 @@ soup_auth_get_realm (SoupAuth *auth)
 	return SOUP_AUTH_GET_CLASS (auth)->get_realm (auth);
 }
 
+/**
+ * soup_auth_is_authenticated:
+ * @auth: a #SoupAuth
+ *
+ * Tests if @auth has been given a username and password
+ *
+ * Return value: %TRUE if @auth has been given a username and password
+ **/
 gboolean
 soup_auth_is_authenticated (SoupAuth *auth)
 {
@@ -112,6 +157,16 @@ soup_auth_is_authenticated (SoupAuth *auth)
 	return SOUP_AUTH_GET_CLASS (auth)->is_authenticated (auth);
 }
 
+/**
+ * soup_auth_get_authorization:
+ * @auth: a #SoupAuth
+ * @msg: the #SoupMessage to be authorized
+ *
+ * Generates an appropriate "Authorization" header for @msg. (This
+ * will only be called if soup_auth_is_authenticated() returns %TRUE.)
+ *
+ * Return value: the "Authorization" header, which must be freed.
+ **/
 char *
 soup_auth_get_authorization (SoupAuth *auth, SoupMessage *msg)
 {
@@ -121,6 +176,20 @@ soup_auth_get_authorization (SoupAuth *auth, SoupMessage *msg)
 	return SOUP_AUTH_GET_CLASS (auth)->get_authorization (auth, msg);
 }
 
+/**
+ * soup_auth_get_protection_space:
+ * @auth: a #SoupAuth
+ * @source_uri: the URI of the request that @auth was generated in
+ * response to.
+ *
+ * Returns a list of paths on the server which @auth extends over.
+ * (All subdirectories of these paths are also assumed to be part
+ * of @auth's protection space, unless otherwise discovered not to
+ * be.)
+ *
+ * Return value: the list of paths, which must be freed with
+ * soup_auth_free_protection_space().
+ **/
 GSList *
 soup_auth_get_protection_space (SoupAuth *auth, const SoupUri *source_uri)
 {
@@ -130,6 +199,13 @@ soup_auth_get_protection_space (SoupAuth *auth, const SoupUri *source_uri)
 	return SOUP_AUTH_GET_CLASS (auth)->get_protection_space (auth, source_uri);
 }
 
+/**
+ * soup_auth_free_protection_space:
+ * @auth: a #SoupAuth
+ * @space: the return value from soup_auth_get_protection_space()
+ *
+ * Frees @space.
+ **/
 void
 soup_auth_free_protection_space (SoupAuth *auth, GSList *space)
 {
diff --git a/libsoup/soup-connection.c b/libsoup/soup-connection.c
index 4246a884..3129bb79 100644
--- a/libsoup/soup-connection.c
+++ b/libsoup/soup-connection.c
@@ -604,7 +604,10 @@ soup_connection_disconnect (SoupConnection *conn)
  * soup_connection_is_in_use:
  * @conn: a connection
  *
- * Return value: whether or not @conn is being used.
+ * Tests whether or not @conn is in use.
+ *
+ * Return value: %TRUE if there is currently a request being processed
+ * on @conn.
  **/
 gboolean
 soup_connection_is_in_use (SoupConnection *conn)
@@ -618,6 +621,8 @@ soup_connection_is_in_use (SoupConnection *conn)
  * soup_connection_last_used:
  * @conn: a #SoupConnection.
  *
+ * Returns the last time a response was received on @conn.
+ *
  * Return value: the last time a response was received on @conn, or 0
  * if @conn has not been used yet.
  */
@@ -748,7 +753,7 @@ soup_connection_authenticate (SoupConnection *conn, SoupMessage *msg,
 }
 
 /**
- * soup_connection_authenticate:
+ * soup_connection_reauthenticate:
  * @conn: a #SoupConnection
  * @msg: the message to authenticate
  * @auth_type: type of authentication to use
diff --git a/libsoup/soup-connection.h b/libsoup/soup-connection.h
index 92583b4a..959bceb9 100644
--- a/libsoup/soup-connection.h
+++ b/libsoup/soup-connection.h
@@ -54,7 +54,7 @@ GType soup_connection_get_type (void);
 SoupConnection *soup_connection_new            (const char       *propname1,
 						...);
 
-typedef void  (*SoupConnectionCallback)        (SoupConnection   *sock,
+typedef void  (*SoupConnectionCallback)        (SoupConnection   *conn,
 						guint             status,
 						gpointer          data);
 
diff --git a/libsoup/soup-dns.c b/libsoup/soup-dns.c
index 8cbc3708..050327da 100644
--- a/libsoup/soup-dns.c
+++ b/libsoup/soup-dns.c
@@ -59,6 +59,13 @@ copy_hostent (struct hostent *h)
 			    h->h_length, h->h_addr_list[0]);
 }
 
+/**
+ * soup_dns_free_hostent:
+ * @h: a #hostent
+ *
+ * Frees @h. Use this to free the return value from
+ * soup_dns_entry_get_hostent().
+ **/
 void
 soup_dns_free_hostent (struct hostent *h)
 {
@@ -119,6 +126,17 @@ new_hostent_from_phys (const char *addr)
 	return NULL;
 }
 
+/**
+ * soup_dns_ntop:
+ * @addr: pointer to address data (eg, an #in_addr_t)
+ * @family: address family of @addr 
+ *
+ * Converts @addr into textual form (eg, "141.213.8.59"), like the
+ * standard library function inet_ntop(), except that the returned
+ * string must be freed.
+ *
+ * Return value: the text form or @addr, which must be freed.
+ **/
 char *
 soup_dns_ntop (gconstpointer addr, int family)
 {
@@ -423,9 +441,9 @@ soup_dns_lookup_entry (const char *name)
  *   (eg, 141.213.8.59).
  *
  * Begins asynchronous resolution of @name. The caller should
- * periodically call soup_entry_check_lookup() to see if it is done,
- * and call soup_entry_get_hostent() when soup_entry_check_lookup()
- * returns %TRUE.
+ * periodically call soup_dns_entry_check_lookup() to see if it is
+ * done, and call soup_dns_entry_get_hostent() when
+ * soup_dns_entry_check_lookup() returns %TRUE.
  *
  * Currently, this routine forks and does the lookup, which can cause
  * some problems. In general, this will work ok for most programs most
@@ -433,7 +451,7 @@ soup_dns_lookup_entry (const char *name)
  * systems that copy the entire process when forking.
  *
  * Returns: a #SoupDNSEntry, which will be freed when you call
- * soup_entry_get_hostent() or soup_entry_cancel_lookup().
+ * soup_dns_entry_get_hostent() or soup_dns_entry_cancel_lookup().
  **/
 SoupDNSEntry *
 soup_dns_entry_from_name (const char *name)
@@ -517,9 +535,9 @@ soup_dns_entry_from_name (const char *name)
  * @family: address family of @addr
  *
  * Begins asynchronous resolution of @addr. The caller should
- * periodically call soup_entry_check_lookup() to see if it is done,
- * and call soup_entry_get_hostent() when soup_entry_check_lookup()
- * returns %TRUE.
+ * periodically call soup_dns_entry_check_lookup() to see if it is
+ * done, and call soup_dns_entry_get_hostent() when
+ * soup_dns_entry_check_lookup() returns %TRUE.
  *
  * Currently, this routine forks and does the lookup, which can cause
  * some problems. In general, this will work ok for most programs most
@@ -527,7 +545,7 @@ soup_dns_entry_from_name (const char *name)
  * systems that copy the entire process when forking.
  *
  * Returns: a #SoupDNSEntry, which will be freed when you call
- * soup_entry_get_hostent() or soup_entry_cancel_lookup().
+ * soup_dns_entry_get_hostent() or soup_dns_entry_cancel_lookup().
  **/
 SoupDNSEntry *
 soup_dns_entry_from_addr (gconstpointer addr, int family)
@@ -663,6 +681,15 @@ check_hostent (SoupDNSEntry *entry, gboolean block)
 	soup_dns_unlock ();
 }
 
+/**
+ * soup_dns_entry_check_lookup:
+ * @entry: a #SoupDNSEntry
+ *
+ * Checks if @entry has finished resolving
+ *
+ * Return value: %TRUE if @entry has finished resolving (either
+ * successfully or not)
+ **/
 gboolean
 soup_dns_entry_check_lookup (SoupDNSEntry *entry)
 {
@@ -674,6 +701,16 @@ soup_dns_entry_check_lookup (SoupDNSEntry *entry)
 	return entry->resolved;
 }
 
+/**
+ * soup_dns_entry_get_hostent:
+ * @entry: a #SoupDNSEntry
+ *
+ * Extracts a #hostent from @entry. If @entry had not already finished
+ * resolving, soup_dns_entry_get_hostent() will block until it does.
+ *
+ * Return value: the #hostent (which must be freed with
+ * soup_dns_free_hostent()), or %NULL if it couldn't be resolved.
+ **/
 struct hostent *
 soup_dns_entry_get_hostent (SoupDNSEntry *entry)
 {
@@ -686,6 +723,12 @@ soup_dns_entry_get_hostent (SoupDNSEntry *entry)
 	return h;
 }
 
+/**
+ * soup_dns_entry_cancel_lookup:
+ * @entry: a #SoupDNSEntry
+ *
+ * Cancels the lookup for @entry.
+ **/
 void
 soup_dns_entry_cancel_lookup (SoupDNSEntry *entry)
 {
diff --git a/libsoup/soup-gnutls.c b/libsoup/soup-gnutls.c
index b895f951..4a0aa58b 100644
--- a/libsoup/soup-gnutls.c
+++ b/libsoup/soup-gnutls.c
@@ -331,6 +331,19 @@ THROW_CREATE_ERROR:
 	return FALSE;
 }
 
+/**
+ * soup_ssl_wrap_iochannel:
+ * @sock: a #GIOChannel wrapping a TCP socket.
+ * @type: whether this is a client or server socket
+ * @hostname: the hostname of the remote machine
+ * @cred_pointer: a client or server credentials structure
+ *
+ * This attempts to wrap a new #GIOChannel around @sock that
+ * will SSL-encrypt/decrypt all traffic through it.
+ *
+ * Return value: an SSL-encrypting #GIOChannel, or %NULL on
+ * failure.
+ **/
 GIOChannel *
 soup_ssl_wrap_iochannel (GIOChannel *sock, SoupSSLType type,
 			 const char *hostname, gpointer cred_pointer)
@@ -393,6 +406,21 @@ soup_ssl_wrap_iochannel (GIOChannel *sock, SoupSSLType type,
 	return NULL;
 }
 
+/**
+ * soup_ssl_get_client_credentials:
+ * @ca_file: path to a file containing X509-encoded Certificate
+ * Authority certificates.
+ *
+ * Creates an opaque client credentials object which can later be
+ * passed to soup_ssl_wrap_iochannel().
+ *
+ * If @ca_file is non-%NULL, any certificate received from a server
+ * must be signed by one of the CAs in the file, or an error will
+ * be returned.
+ *
+ * Return value: the client credentials, which must be freed with
+ * soup_ssl_free_client_credentials().
+ **/
 gpointer
 soup_ssl_get_client_credentials (const char *ca_file)
 {
@@ -422,6 +450,13 @@ soup_ssl_get_client_credentials (const char *ca_file)
 	return cred;
 }
 
+/**
+ * soup_ssl_free_client_credentials:
+ * @client_creds: a client credentials structure returned by
+ * soup_ssl_get_client_credentials().
+ *
+ * Frees @client_creds.
+ **/
 void
 soup_ssl_free_client_credentials (gpointer client_creds)
 {
@@ -431,6 +466,19 @@ soup_ssl_free_client_credentials (gpointer client_creds)
 	g_free (cred);
 }
 
+/**
+ * soup_ssl_get_server_credentials:
+ * @cert_file: path to a file containing an X509-encoded server
+ * certificate
+ * @key_file: path to a file containing an X509-encoded key for
+ * @cert_file.
+ *
+ * Creates an opaque server credentials object which can later be
+ * passed to soup_ssl_wrap_iochannel().
+ *
+ * Return value: the server credentials, which must be freed with
+ * soup_ssl_free_server_credentials().
+ **/
 gpointer
 soup_ssl_get_server_credentials (const char *cert_file, const char *key_file)
 {
@@ -458,6 +506,13 @@ soup_ssl_get_server_credentials (const char *cert_file, const char *key_file)
 	return cred;
 }
 
+/**
+ * soup_ssl_free_server_credentials:
+ * @server_creds: a server credentials structure returned by
+ * soup_ssl_get_server_credentials().
+ *
+ * Frees @server_creds.
+ **/
 void
 soup_ssl_free_server_credentials (gpointer server_creds)
 {
diff --git a/libsoup/soup-message-client-io.c b/libsoup/soup-message-client-io.c
index 8dd171a2..fdc64294 100644
--- a/libsoup/soup-message-client-io.c
+++ b/libsoup/soup-message-client-io.c
@@ -157,6 +157,17 @@ get_request_headers (SoupMessage *req, GString *header,
 		req->priv->msg_flags |= SOUP_MESSAGE_EXPECT_CONTINUE;
 }
 
+/**
+ * soup_message_send_request:
+ * @req: a #SoupMessage
+ * @sock: the #SoupSocket to send @req on
+ * @is_via_proxy: %TRUE if @sock is a connection to a proxy server
+ * rather than a direct connection to the desired HTTP server
+ *
+ * Begins the process of sending @msg across @sock. (If @sock is
+ * synchronous, then soup_message_send_request() won't return until
+ * the response has been received.)
+ **/
 void
 soup_message_send_request (SoupMessage *req, SoupSocket *sock,
 			   gboolean is_via_proxy)
diff --git a/libsoup/soup-message-handlers.c b/libsoup/soup-message-handlers.c
index e128dd8e..89ccbf81 100644
--- a/libsoup/soup-message-handlers.c
+++ b/libsoup/soup-message-handlers.c
@@ -61,12 +61,13 @@ run_handler (SoupMessage     *msg,
 	(*data->handler_cb) (msg, data->user_data);
 }
 
-/*
- * Run each handler with matching criteria. If a handler requeues a
- * message, we stop processing and terminate the current request.
+/**
+ * soup_message_run_handlers:
+ * @msg: a #SoupMessage
+ * @invoke_phase: which group of handlers to run
  *
- * After running all handlers, if there is an error set or the invoke
- * phase was post_body, issue the final callback.
+ * Run each @invoke_phase handler on @msg. If a handler requeues the
+ * message, we stop processing at that point.
  */
 void
 soup_message_run_handlers (SoupMessage *msg, SoupHandlerPhase invoke_phase)
@@ -126,6 +127,17 @@ add_handler (SoupMessage           *msg,
 		g_slist_append (msg->priv->content_handlers, data);
 }
 
+/**
+ * soup_message_add_header_handler:
+ * @msg: a #SoupMessage
+ * @header: HTTP response header to match against
+ * @phase: processing phase to run the handler in
+ * @handler_cb: the handler
+ * @user_data: data to pass to @handler_cb
+ *
+ * Adds a handler to @msg for messages containing the given response
+ * header.
+ **/
 void
 soup_message_add_header_handler (SoupMessage           *msg,
 				 const char            *header,
@@ -142,6 +154,17 @@ soup_message_add_header_handler (SoupMessage           *msg,
 		     header, 0, 0);
 }
 
+/**
+ * soup_message_add_status_code_handler:
+ * @msg: a #SoupMessage
+ * @status_code: HTTP status code to match against
+ * @phase: processing phase to run the handler in
+ * @handler_cb: the handler
+ * @user_data: data to pass to @handler_cb
+ *
+ * Adds a handler to @msg for messages receiving the given status
+ * code.
+ **/
 void
 soup_message_add_status_code_handler (SoupMessage           *msg,
 				      guint                  status_code,
@@ -158,6 +181,17 @@ soup_message_add_status_code_handler (SoupMessage           *msg,
 		     NULL, status_code, 0);
 }
 
+/**
+ * soup_message_add_status_class_handler:
+ * @msg: a #SoupMessage
+ * @status_class: HTTP status code class to match against
+ * @phase: processing phase to run the handler in
+ * @handler_cb: the handler
+ * @user_data: data to pass to @handler_cb
+ *
+ * Adds a handler to @msg for messages receiving a status code in
+ * the given class.
+ **/
 void
 soup_message_add_status_class_handler (SoupMessage           *msg,
 				       SoupStatusClass        status_class,
@@ -174,11 +208,20 @@ soup_message_add_status_class_handler (SoupMessage           *msg,
 		     NULL, 0, status_class);
 }
 
+/**
+ * soup_message_add_handler:
+ * @msg: a #SoupMessage
+ * @phase: processing phase to run the handler in
+ * @handler_cb: the handler
+ * @user_data: data to pass to @handler_cb
+ *
+ * Adds a handler to @msg for all messages
+ **/
 void
-soup_message_add_handler (SoupMessage      *msg,
-			  SoupHandlerPhase  phase,
-			  SoupMessageCallbackFn    handler_cb,
-			  gpointer          user_data)
+soup_message_add_handler (SoupMessage           *msg,
+			  SoupHandlerPhase       phase,
+			  SoupMessageCallbackFn  handler_cb,
+			  gpointer               user_data)
 {
 	g_return_if_fail (SOUP_IS_MESSAGE (msg));
 	g_return_if_fail (handler_cb != NULL);
@@ -186,6 +229,15 @@ soup_message_add_handler (SoupMessage      *msg,
 	add_handler (msg, phase, handler_cb, user_data, 0, NULL, 0, 0);
 }
 
+/**
+ * soup_message_remove_handler:
+ * @msg: a #SoupMessage
+ * @phase: processing phase to run the handler in
+ * @handler_cb: the handler
+ * @user_data: data to pass to @handler_cb
+ *
+ * Removes all matching handlers from @msg
+ **/
 void
 soup_message_remove_handler (SoupMessage           *msg,
 			     SoupHandlerPhase       phase,
diff --git a/libsoup/soup-message-io.c b/libsoup/soup-message-io.c
index ae0168da..a8ea957c 100644
--- a/libsoup/soup-message-io.c
+++ b/libsoup/soup-message-io.c
@@ -91,6 +91,13 @@ io_cleanup (SoupMessage *msg)
 	msg->priv->io_data = NULL;
 }
 
+/**
+ * soup_message_io_stop:
+ * @msg: a #SoupMessage
+ *
+ * Immediately stops I/O on msg; if the connection would be left in an
+ * inconsistent state, it will be closed.
+ **/
 void
 soup_message_io_stop (SoupMessage *msg)
 {
@@ -676,6 +683,18 @@ new_iostate (SoupMessage *msg, SoupSocket *sock, SoupMessageIOMode mode,
 	return io;
 }
 
+/**
+ * soup_message_io_client:
+ * @msg: a #SoupMessage
+ * @sock: socket to send @msg across
+ * @get_headers_cb: callback function to generate request headers
+ * @parse_headers_cb: callback function to parse response headers
+ * @user_data: data to pass to the callbacks
+ *
+ * Begins the process of sending @msg across @sock.
+ *
+ * Don't call this. Use soup_message_send_request().
+ **/
 void
 soup_message_io_client (SoupMessage *msg, SoupSocket *sock,
 			SoupMessageGetHeadersFn get_headers_cb,
@@ -694,6 +713,18 @@ soup_message_io_client (SoupMessage *msg, SoupSocket *sock,
 	io_write (sock, msg);
 }
 
+/**
+ * soup_message_io_server:
+ * @msg: an empty #SoupServerMessage
+ * @sock: socket to receive a request on
+ * @get_headers_cb: callback function to generate response headers
+ * @parse_headers_cb: callback function to parse request headers
+ * @user_data: data to pass to the callbacks
+ *
+ * Begins the process of receiving a request from @sock into @msg.
+ *
+ * Don't use this. Use soup_message_receive_request() instead.
+ **/
 void
 soup_message_io_server (SoupMessage *msg, SoupSocket *sock,
 			SoupMessageGetHeadersFn get_headers_cb,
@@ -712,6 +743,12 @@ soup_message_io_server (SoupMessage *msg, SoupSocket *sock,
 	io_read (sock, msg);
 }
 
+/**
+ * soup_message_io_pause:
+ * @msg: a #SoupMessage
+ *
+ * Pauses I/O on @msg.
+ **/
 void  
 soup_message_io_pause (SoupMessage *msg)
 {
@@ -729,6 +766,12 @@ soup_message_io_pause (SoupMessage *msg)
 	}
 }
 
+/**
+ * soup_message_io_unpause:
+ * @msg: a #SoupMessage
+ *
+ * Resumes I/O on @msg.
+ **/
 void  
 soup_message_io_unpause (SoupMessage *msg)
 {
diff --git a/libsoup/soup-message-private.h b/libsoup/soup-message-private.h
index 1488867f..c17bc78d 100644
--- a/libsoup/soup-message-private.h
+++ b/libsoup/soup-message-private.h
@@ -25,7 +25,6 @@ struct SoupMessagePrivate {
 void             soup_message_run_handlers     (SoupMessage      *msg,
 						SoupHandlerPhase  phase);
 
-void             soup_message_cleanup          (SoupMessage      *req);
 void             soup_message_cleanup_response (SoupMessage      *req);
 
 
diff --git a/libsoup/soup-message-queue.c b/libsoup/soup-message-queue.c
index 9b89381e..d730dc30 100644
--- a/libsoup/soup-message-queue.c
+++ b/libsoup/soup-message-queue.c
@@ -21,6 +21,8 @@ struct SoupMessageQueue {
 /**
  * soup_message_queue_new:
  *
+ * Creates a new #SoupMessageQueue
+ *
  * Return value: a new #SoupMessageQueue object
  **/
 SoupMessageQueue *
@@ -145,7 +147,9 @@ queue_remove_internal (SoupMessageQueue *queue, SoupMessageQueueIter *iter)
  * @queue: a queue
  * @iter: pointer to an initialized #SoupMessageQueueIter
  *
- * Return value: the next element of @queue, or %NULL if there are no more.
+ * Returns the next element of @queue
+ *
+ * Return value: the next element, or %NULL if there are no more.
  **/
 SoupMessage *
 soup_message_queue_next (SoupMessageQueue *queue, SoupMessageQueueIter *iter)
@@ -196,6 +200,13 @@ soup_message_queue_remove (SoupMessageQueue *queue, SoupMessageQueueIter *iter)
 	return msg;
 }
 
+/**
+ * soup_message_queue_remove_message:
+ * @queue: a queue
+ * @msg: a #SoupMessage
+ *
+ * Removes the indicated message from @queue.
+ **/
 void
 soup_message_queue_remove_message (SoupMessageQueue *queue, SoupMessage *msg)
 {
diff --git a/libsoup/soup-message-server-io.c b/libsoup/soup-message-server-io.c
index 8a114426..96d8dc84 100644
--- a/libsoup/soup-message-server-io.c
+++ b/libsoup/soup-message-server-io.c
@@ -147,6 +147,13 @@ get_response_headers (SoupMessage *msg, GString *headers,
 	g_string_append (headers, "\r\n");
 }
 
+/**
+ * soup_message_read_request:
+ * @req: an empty #SoupServerMessage
+ * @sock: socket to receive the request on
+ *
+ * Begins the process of receiving a request from @sock into @req.
+ **/
 void
 soup_message_read_request (SoupMessage *req, SoupSocket *sock)
 {
diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c
index aa256df1..2960f74a 100644
--- a/libsoup/soup-message.c
+++ b/libsoup/soup-message.c
@@ -309,18 +309,39 @@ soup_message_set_response (SoupMessage   *msg,
 	msg->response.length = resp_length;
 }
 
+/**
+ * soup_message_wrote_informational:
+ * @msg: a #SoupMessage
+ *
+ * Emits the %wrote_informational signal, indicating that the IO layer
+ * finished writing an informational (1xx) response for @msg.
+ **/
 void
 soup_message_wrote_informational (SoupMessage *msg)
 {
 	g_signal_emit (msg, signals[WROTE_INFORMATIONAL], 0);
 }
 
+/**
+ * soup_message_wrote_headers:
+ * @msg: a #SoupMessage
+ *
+ * Emits the %wrote_headers signal, indicating that the IO layer
+ * finished writing the (non-informational) headers for @msg.
+ **/
 void
 soup_message_wrote_headers (SoupMessage *msg)
 {
 	g_signal_emit (msg, signals[WROTE_HEADERS], 0);
 }
 
+/**
+ * soup_message_wrote_chunk:
+ * @msg: a #SoupMessage
+ *
+ * Emits the %wrote_chunk signal, indicating that the IO layer
+ * finished writing a chunk of @msg's body.
+ **/
 void
 soup_message_wrote_chunk (SoupMessage *msg)
 {
@@ -335,12 +356,26 @@ wrote_body (SoupMessage *req)
 	g_object_unref (req);
 }
 
+/**
+ * soup_message_wrote_body:
+ * @msg: a #SoupMessage
+ *
+ * Emits the %wrote_body signal, indicating that the IO layer finished
+ * writing the body for @msg.
+ **/
 void
 soup_message_wrote_body (SoupMessage *msg)
 {
 	g_signal_emit (msg, signals[WROTE_BODY], 0);
 }
 
+/**
+ * soup_message_got_informational:
+ * @msg: a #SoupMessage
+ *
+ * Emits the %got_informational signal, indicating that the IO layer
+ * read a complete informational (1xx) response for @msg.
+ **/
 void
 soup_message_got_informational (SoupMessage *msg)
 {
@@ -357,6 +392,13 @@ got_headers (SoupMessage *req)
 	g_object_unref (req);
 }
 
+/**
+ * soup_message_got_headers:
+ * @msg: a #SoupMessage
+ *
+ * Emits the %got_headers signal, indicating that the IO layer
+ * finished reading the (non-informational) headers for @msg.
+ **/
 void
 soup_message_got_headers (SoupMessage *msg)
 {
@@ -373,6 +415,13 @@ got_chunk (SoupMessage *req)
 	g_object_unref (req);
 }
 
+/**
+ * soup_message_got_chunk:
+ * @msg: a #SoupMessage
+ *
+ * Emits the %got_chunk signal, indicating that the IO layer finished
+ * reading a chunk of @msg's body.
+ **/
 void
 soup_message_got_chunk (SoupMessage *msg)
 {
@@ -389,6 +438,13 @@ got_body (SoupMessage *req)
 	g_object_unref (req);
 }
 
+/**
+ * soup_message_got_body:
+ * @msg: a #SoupMessage
+ *
+ * Emits the %got_body signal, indicating that the IO layer finished
+ * reading the body for @msg.
+ **/
 void
 soup_message_got_body (SoupMessage *msg)
 {
@@ -401,6 +457,13 @@ restarted (SoupMessage *req)
 	soup_message_io_stop (req);
 }
 
+/**
+ * soup_message_restarted:
+ * @msg: a #SoupMessage
+ *
+ * Emits the %restarted signal, indicating that @msg should be
+ * requeued.
+ **/
 void
 soup_message_restarted (SoupMessage *msg)
 {
@@ -414,6 +477,13 @@ finished (SoupMessage *req)
 	req->status = SOUP_MESSAGE_STATUS_FINISHED;
 }
 
+/**
+ * soup_message_finished:
+ * @msg: a #SoupMessage
+ *
+ * Emits the %finished signal, indicating that @msg has been completely
+ * processed.
+ **/
 void
 soup_message_finished (SoupMessage *msg)
 {
@@ -430,6 +500,13 @@ free_header_list (gpointer name, gpointer vals, gpointer user_data)
 	return TRUE;
 }
 
+/**
+ * soup_message_clear_headers:
+ * @hash: a header table (the %request_headers or %response_headers
+ * field of a #SoupMessage)
+ *
+ * Clears @hash.
+ **/
 void
 soup_message_clear_headers (GHashTable *hash)
 {
@@ -438,6 +515,15 @@ soup_message_clear_headers (GHashTable *hash)
 	g_hash_table_foreach_remove (hash, free_header_list, NULL);
 }
 
+/**
+ * soup_message_remove_header:
+ * @hash: a header table (the %request_headers or %response_headers
+ * field of a #SoupMessage)
+ * @name: the header name to remove
+ *
+ * Removes @name from @hash. If there are multiple values for @name,
+ * they are all removed.
+ **/
 void
 soup_message_remove_header (GHashTable *hash, const char *name)
 {
@@ -452,6 +538,17 @@ soup_message_remove_header (GHashTable *hash, const char *name)
 	}
 }
 
+/**
+ * soup_message_add_header:
+ * @hash: a header table (the %request_headers or %response_headers
+ * field of a #SoupMessage)
+ * @name: the header name to add
+ * @value: the value of the new header
+ *
+ * Adds a header with name @name and value @value to @hash. If there
+ * was already a header with name @name, this one does not replace it,
+ * it is merely added to it.
+ **/
 void
 soup_message_add_header (GHashTable *hash, const char *name, const char *value)
 {
@@ -473,14 +570,14 @@ soup_message_add_header (GHashTable *hash, const char *name, const char *value)
 
 /**
  * soup_message_get_header:
- * @hash: a header hash table
+ * @hash: a header table (the %request_headers or %response_headers
+ * field of a #SoupMessage)
  * @name: header name.
  * 
- * Lookup the first transport header in @hash with a key equal to
- * @name.
+ * Finds the first header in @hash with name @name.
  * 
  * Return value: the header's value or %NULL if not found.
- */
+ **/
 const char *
 soup_message_get_header (GHashTable *hash, const char *name)
 {
@@ -498,15 +595,15 @@ soup_message_get_header (GHashTable *hash, const char *name)
 
 /**
  * soup_message_get_header_list:
- * @hash: a header hash table
+ * @hash: a header table (the %request_headers or %response_headers
+ * field of a #SoupMessage)
  * @name: header name.
  * 
- * Lookup the all transport request headers in @hash with a key equal
- * to @name.
+ * Finds all headers in @hash with name @name.
  * 
- * Return value: a const pointer to a #GSList of header values or
- * %NULL if not found.
- */
+ * Return value: a (possibly empty) list of values of headers with
+ * name @name. The caller should not modify or free this list.
+ **/
 const GSList *
 soup_message_get_header_list (GHashTable *hash, const char *name)
 {
@@ -533,6 +630,17 @@ foreach_value_in_list (gpointer name, gpointer value, gpointer user_data)
 	}
 }
 
+/**
+ * soup_message_foreach_header:
+ * @hash: a header table (the %request_headers or %response_headers
+ * field of a #SoupMessage)
+ * @func: callback function to run for each header
+ * @user_data: data to pass to @func
+ * 
+ * Calls @func once for each header value in @hash. (If there are
+ * headers will multiple values, @func will be called once on each
+ * value.)
+ **/
 void
 soup_message_foreach_header (GHashTable *hash, GHFunc func, gpointer user_data)
 {
@@ -546,6 +654,14 @@ soup_message_foreach_header (GHashTable *hash, GHFunc func, gpointer user_data)
 	g_hash_table_foreach (hash, foreach_value_in_list, &data);
 }
 
+/**
+ * soup_message_cleanup_response:
+ * @req: a #SoupMessage
+ *
+ * Cleans up all response data on @req, so that the request can be sent
+ * again and receive a new response. (Eg, as a result of a redirect or
+ * authorization request.)
+ **/
 void
 soup_message_cleanup_response (SoupMessage *req)
 {
@@ -567,6 +683,13 @@ soup_message_cleanup_response (SoupMessage *req)
 	}
 }
 
+/**
+ * soup_message_set_flags:
+ * @msg: a #SoupMessage
+ * @flags: a set of #SoupMessageFlags values
+ *
+ * Sets the specified flags on @msg.
+ **/
 void
 soup_message_set_flags (SoupMessage *msg, guint flags)
 {
@@ -575,6 +698,14 @@ soup_message_set_flags (SoupMessage *msg, guint flags)
 	msg->priv->msg_flags = flags;
 }
 
+/**
+ * soup_message_get_flags:
+ * @msg: a #SoupMessage
+ *
+ * Gets the flags on @msg
+ *
+ * Return value: the flags
+ **/
 guint
 soup_message_get_flags (SoupMessage *msg)
 {
@@ -583,6 +714,15 @@ soup_message_get_flags (SoupMessage *msg)
 	return msg->priv->msg_flags;
 }
 
+/**
+ * soup_message_set_http_version:
+ * @msg: a #SoupMessage
+ * @version: the HTTP version
+ *
+ * Sets the HTTP version on @msg. The default version is
+ * %SOUP_HTTP_1_1. Setting it to %SOUP_HTTP_1_0 will prevent certain
+ * functionality from being used.
+ **/
 void
 soup_message_set_http_version (SoupMessage *msg, SoupHttpVersion version)
 {
@@ -591,6 +731,15 @@ soup_message_set_http_version (SoupMessage *msg, SoupHttpVersion version)
 	msg->priv->http_version = version;
 }
 
+/**
+ * soup_message_get_http_version:
+ * @msg: a #SoupMessage
+ *
+ * Gets the HTTP version of @msg. This is the minimum of the
+ * version from the request and the version from the response.
+ *
+ * Return value: the HTTP version
+ **/
 SoupHttpVersion
 soup_message_get_http_version (SoupMessage *msg)
 {
@@ -599,6 +748,15 @@ soup_message_get_http_version (SoupMessage *msg)
 	return msg->priv->http_version;
 }
 
+/**
+ * soup_message_is_keepalive:
+ * @msg: a #SoupMessage
+ *
+ * Determines whether or not @msg's connection can be kept alive for
+ * further requests after processing @msg.
+ *
+ * Return value: %TRUE or %FALSE.
+ **/
 gboolean
 soup_message_is_keepalive (SoupMessage *msg)
 {
@@ -635,6 +793,14 @@ soup_message_is_keepalive (SoupMessage *msg)
 	}
 }
 
+/**
+ * soup_message_set_uri:
+ * @msg: a #SoupMessage
+ * @new_uri: the new #SoupUri
+ *
+ * Changes the URI that @msg is directed to (generally as a result
+ * of a redirect).
+ **/
 void
 soup_message_set_uri (SoupMessage *msg, const SoupUri *new_uri)
 {
@@ -651,6 +817,14 @@ soup_message_set_uri (SoupMessage *msg, const SoupUri *new_uri)
 	msg->priv->uri = soup_uri_copy (new_uri);
 }
 
+/**
+ * soup_message_get_uri:
+ * @msg: a #SoupMessage
+ *
+ * Gets @msg's URI
+ *
+ * Return value: the URI @msg is targeted for.
+ **/
 const SoupUri *
 soup_message_get_uri (SoupMessage *msg)
 {
@@ -659,6 +833,14 @@ soup_message_get_uri (SoupMessage *msg)
 	return msg->priv->uri;
 }
 
+/**
+ * soup_message_set_status:
+ * @msg: a #SoupMessage
+ * @status_code: an HTTP status code
+ *
+ * Sets @msg's status code to @status_code. If @status_code is a
+ * known value, it will also set @msg's reason_phrase.
+ **/
 void
 soup_message_set_status (SoupMessage *msg, guint status_code)
 {
@@ -671,6 +853,14 @@ soup_message_set_status (SoupMessage *msg, guint status_code)
 	msg->reason_phrase = g_strdup (soup_status_get_phrase (status_code));
 }
 
+/**
+ * soup_message_set_status_full:
+ * @msg: a #SoupMessage
+ * @status_code: an HTTP status code
+ * @reason_phrase: a description of the status
+ *
+ * Sets @msg's status code and reason phrase.
+ **/
 void
 soup_message_set_status_full (SoupMessage *msg,
 			      guint        status_code,
@@ -687,6 +877,16 @@ soup_message_set_status_full (SoupMessage *msg,
 }
 
 
+/**
+ * soup_message_add_chunk:
+ * @msg: a #SoupMessage
+ * @owner: the ownership of @body
+ * @body: body data
+ * @length: length of @body
+ *
+ * Adds a chunk of response data to @body. (Note that currently
+ * there is no way to send a request using chunked encoding.)
+ **/
 void
 soup_message_add_chunk (SoupMessage   *msg,
 			SoupOwnership  owner,
@@ -717,12 +917,30 @@ soup_message_add_chunk (SoupMessage   *msg,
 	}
 }
 
+/**
+ * soup_message_add_final_chunk:
+ * @msg: a #SoupMessage
+ *
+ * Adds a final, empty chunk of response data to @body. This must
+ * be called after adding the last real chunk, to indicate that
+ * there is no more data.
+ **/
 void
 soup_message_add_final_chunk (SoupMessage *msg)
 {
 	soup_message_add_chunk (msg, SOUP_BUFFER_STATIC, NULL, 0);
 }
 
+/**
+ * soup_message_pop_chunk:
+ * @msg: a #SoupMessage
+ *
+ * Pops a chunk of response data from @msg's chunk list. The caller
+ * must free @chunk itself, and must handle the data in @chunk
+ * according to its %ownership.
+ *
+ * Return value: the chunk, or %NULL if there are no chunks left.
+ **/
 SoupDataBuffer *
 soup_message_pop_chunk (SoupMessage *msg)
 {
diff --git a/libsoup/soup-message.h b/libsoup/soup-message.h
index a248e43a..af2b28d8 100644
--- a/libsoup/soup-message.h
+++ b/libsoup/soup-message.h
@@ -138,26 +138,12 @@ void             soup_message_set_uri             (SoupMessage       *msg,
 
 typedef enum {
 	/*
-	 * SOUP_MESSAGE_NO_PIPELINE: 
-	 * Use a currently unused connection or establish a new 
-	 * connection when issuing this request.
-	 */
-	SOUP_MESSAGE_NO_PIPELINE      = (1 << 0),
-
-	/*
 	 * SOUP_MESSAGE_NO_REDIRECT: 
 	 * Do not follow redirection responses.
 	 */
 	SOUP_MESSAGE_NO_REDIRECT      = (1 << 1),
 
 	/*
-	 * SOUP_MESSAGE_NO_COOKIE:
-	 * Do not send cookie information with request, and do not 
-	 * store cookie information from the response.
-	 */
-	SOUP_MESSAGE_NO_COOKIE        = (1 << 2),
-
-	/*
 	 * SOUP_MESSAGE_OVERWRITE_CHUNKS:
 	 * Downloaded data chunks should not be stored in the response 
 	 * data buffer.  Instead only send data to SOUP_HANDLER_BODY_CHUNK 
diff --git a/libsoup/soup-method.c b/libsoup/soup-method.c
index 74af5f04..7f9d33d9 100644
--- a/libsoup/soup-method.c
+++ b/libsoup/soup-method.c
@@ -9,8 +9,17 @@
 
 #include "soup-method.h"
 
+/**
+ * soup_method_get_id:
+ * @method: an HTTP method
+ *
+ * Converts @method into a corresponding #SoupMethodId (possibly
+ * %SOUP_METHOD_ID_UNKNOWN).
+ *
+ * Return value: the #SoupMethodId
+ **/
 SoupMethodId
-soup_method_get_id (const gchar *method)
+soup_method_get_id (const char *method)
 {
 	g_return_val_if_fail (method != NULL, SOUP_METHOD_ID_UNKNOWN);
 
diff --git a/libsoup/soup-misc.c b/libsoup/soup-misc.c
index add473fe..500caadd 100644
--- a/libsoup/soup-misc.c
+++ b/libsoup/soup-misc.c
@@ -10,19 +10,36 @@
 
 #include "soup-misc.h"
 
+/**
+ * soup_str_case_hash:
+ * @key: ASCII string to hash
+ *
+ * Hashes @key in a case-insensitive manner.
+ *
+ * Return value: the hash code.
+ **/
 guint
 soup_str_case_hash (gconstpointer key)
 {
 	const char *p = key;
-	guint h = toupper(*p);
+	guint h = g_ascii_toupper(*p);
 
 	if (h)
 		for (p += 1; *p != '\0'; p++)
-			h = (h << 5) - h + toupper(*p);
+			h = (h << 5) - h + g_ascii_toupper(*p);
 
 	return h;
 }
 
+/**
+ * soup_str_case_equal:
+ * @v1: an ASCII string
+ * @v2: another ASCII string
+ *
+ * Compares @v1 and @v2 in a case-insensitive manner
+ *
+ * Return value: %TRUE if they are equal (modulo case)
+ **/
 gboolean
 soup_str_case_equal (gconstpointer v1,
 		     gconstpointer v2)
@@ -30,7 +47,7 @@ soup_str_case_equal (gconstpointer v1,
 	const char *string1 = v1;
 	const char *string2 = v2;
 
-	return g_strcasecmp (string1, string2) == 0;
+	return g_ascii_strcasecmp (string1, string2) == 0;
 }
 
 /* Base64 utils (straight from camel-mime-utils.c) */
diff --git a/libsoup/soup-soap-message.c b/libsoup/soup-soap-message.c
index 6439744c..3d552ac2 100644
--- a/libsoup/soup-soap-message.c
+++ b/libsoup/soup-soap-message.c
@@ -238,7 +238,7 @@ soup_soap_message_start_body (SoupSoapMessage *msg)
 }
 
 /**
- * soup_soap_end_body:
+ * soup_soap_message_end_body:
  * @msg: the %SoupSoapMessage.
  *
  * Closes the SOAP Body element.
@@ -613,7 +613,7 @@ soup_soap_message_add_namespace (SoupSoapMessage *msg, const char *prefix, const
 }
 
 /**
- * soup_soap_set_default_namespace:
+ * soup_soap_message_set_default_namespace:
  * @msg: the %SoupSoapMessage.
  * @ns_uri: the namespace URI.
  *
@@ -699,9 +699,11 @@ soup_soap_message_persist (SoupSoapMessage *msg)
  * @msg: the %SoupSoapMessage.
  * @ns_uri: the namespace URI.
  *
- * Return value: The namespace prefix for @ns_uri or an empty string if @ns_uri
- * is set to the default namespace. If no namespace exists for the URI given,
- * NULL is returned.
+ * Returns the namespace prefix for @ns_uri (or an empty string if
+ * @ns_uri is set to the default namespace)
+ *
+ * Return value: The namespace prefix, or %NULL if no namespace exists
+ * for the URI given.
  */
 const char *
 soup_soap_message_get_namespace_prefix (SoupSoapMessage *msg, const char *ns_uri)
diff --git a/libsoup/soup-socket.c b/libsoup/soup-socket.c
index 2e05a644..1d1aaf4a 100644
--- a/libsoup/soup-socket.c
+++ b/libsoup/soup-socket.c
@@ -319,7 +319,9 @@ get_property (GObject *object, guint prop_id,
  * @optname1: name of first property to set (or %NULL)
  * @...: value of @optname1, followed by additional property/value pairs
  *
- * Return value: a new (disconnected) socket
+ * Creates a new (disconnected) socket
+ *
+ * Return value: the new socket
  **/
 SoupSocket *
 soup_socket_new (const char *optname1, ...)
@@ -727,6 +729,13 @@ soup_socket_server_new (SoupAddress *local_addr, gpointer ssl_creds,
 }
 
 
+/**
+ * soup_socket_disconnect:
+ * @sock: a #SoupSocket
+ *
+ * Disconnects @sock. Any further read or write attempts on it will
+ * fail.
+ **/
 void
 soup_socket_disconnect (SoupSocket *sock)
 {
@@ -771,6 +780,14 @@ soup_socket_disconnect (SoupSocket *sock)
 	g_signal_emit (sock, signals[DISCONNECTED], 0);
 }
 
+/**
+ * soup_socket_is_connected:
+ * @sock: a #SoupSocket
+ *
+ * Tests if @sock is connected to another host
+ *
+ * Return value: %TRUE or %FALSE.
+ **/
 gboolean
 soup_socket_is_connected (SoupSocket *sock)
 {
@@ -779,7 +796,14 @@ soup_socket_is_connected (SoupSocket *sock)
 	return sock->priv->iochannel != NULL;
 }
 
-
+/**
+ * soup_socket_get_local_address:
+ * @sock: a #SoupSocket
+ *
+ * Returns the #SoupAddress corresponding to the local end of @sock.
+ *
+ * Return value: the #SoupAddress
+ **/
 SoupAddress *
 soup_socket_get_local_address (SoupSocket *sock)
 {
@@ -799,6 +823,14 @@ soup_socket_get_local_address (SoupSocket *sock)
 	return sock->priv->local_addr;
 }
 
+/**
+ * soup_socket_get_remote_address:
+ * @sock: a #SoupSocket
+ *
+ * Returns the #SoupAddress corresponding to the remote end of @sock.
+ *
+ * Return value: the #SoupAddress
+ **/
 SoupAddress *
 soup_socket_get_remote_address (SoupSocket *sock)
 {
diff --git a/libsoup/soup-status.c b/libsoup/soup-status.c
index 83b5bad7..48f8f112 100644
--- a/libsoup/soup-status.c
+++ b/libsoup/soup-status.c
@@ -84,6 +84,14 @@ struct {
 	{ 0 }
 };
 
+/**
+ * soup_status_get_phrase:
+ * @status_code: an HTTP status code
+ *
+ * Looks up the stock HTTP description of @status_code.
+ *
+ * Return value: the (English) description of @status_code
+ **/
 const char *
 soup_status_get_phrase (guint status_code)
 {
diff --git a/libsoup/soup-status.h b/libsoup/soup-status.h
index f0154abc..3a727044 100644
--- a/libsoup/soup-status.h
+++ b/libsoup/soup-status.h
@@ -17,12 +17,12 @@ typedef enum {
 	SOUP_STATUS_CLASS_SERVER_ERROR
 } SoupStatusClass;
 
-#define SOUP_STATUS_IS_TRANSPORT_ERROR(x) ((x) >  0   && (x) < 100)
-#define SOUP_STATUS_IS_INFORMATIONAL(x)   ((x) >= 100 && (x) < 200)
-#define SOUP_STATUS_IS_SUCCESSFUL(x)      ((x) >= 200 && (x) < 300)
-#define SOUP_STATUS_IS_REDIRECTION(x)     ((x) >= 300 && (x) < 400)
-#define SOUP_STATUS_IS_CLIENT_ERROR(x)    ((x) >= 400 && (x) < 500)
-#define SOUP_STATUS_IS_SERVER_ERROR(x)    ((x) >= 500 && (x) < 600)
+#define SOUP_STATUS_IS_TRANSPORT_ERROR(status) ((status) >  0   && (status) < 100)
+#define SOUP_STATUS_IS_INFORMATIONAL(status)   ((status) >= 100 && (status) < 200)
+#define SOUP_STATUS_IS_SUCCESSFUL(status)      ((status) >= 200 && (status) < 300)
+#define SOUP_STATUS_IS_REDIRECTION(status)     ((status) >= 300 && (status) < 400)
+#define SOUP_STATUS_IS_CLIENT_ERROR(status)    ((status) >= 400 && (status) < 500)
+#define SOUP_STATUS_IS_SERVER_ERROR(status)    ((status) >= 500 && (status) < 600)
 
 typedef enum {
 	SOUP_STATUS_NONE,
diff --git a/libsoup/soup-uri.c b/libsoup/soup-uri.c
index 8e57f51e..2cfeb3aa 100644
--- a/libsoup/soup-uri.c
+++ b/libsoup/soup-uri.c
@@ -271,6 +271,8 @@ append_uri (GString *str, const char *in, const char *extra_enc_chars,
  * @uri: a #SoupUri
  * @just_path: if %TRUE, output just the path and query portions
  *
+ * Returns a string representing @uri.
+ *
  * Return value: a string representing @uri, which the caller must free.
  **/
 char *
@@ -321,6 +323,14 @@ soup_uri_to_string (const SoupUri *uri, gboolean just_path)
 	return return_result;
 }
 
+/**
+ * soup_uri_copy:
+ * @uri: a #SoupUri
+ *
+ * Copies @uri
+ *
+ * Return value: a copy of @uri, which must be freed with soup_uri_free()
+ **/
 SoupUri *
 soup_uri_copy (const SoupUri *uri)
 {
@@ -343,6 +353,16 @@ soup_uri_copy (const SoupUri *uri)
 	return dup;
 }
 
+/**
+ * soup_uri_copy_root:
+ * @uri: a #SoupUri
+ *
+ * Copies the protocol, host, and port of @uri into a new #SoupUri
+ * (all other fields in the new URI will be empty.)
+ *
+ * Return value: a partial copy of @uri, which must be freed with
+ * soup_uri_free()
+ **/
 SoupUri *
 soup_uri_copy_root (const SoupUri *uri)
 {
@@ -368,6 +388,15 @@ parts_equal (const char *one, const char *two)
 	return !strcmp (one, two);
 }
 
+/**
+ * soup_uri_equal:
+ * @u1: a #SoupUri
+ * @u2: another #SoupUri
+ *
+ * Tests whether or not @u1 and @u2 are equal in all parts
+ *
+ * Return value: %TRUE or %FALSE
+ **/
 gboolean 
 soup_uri_equal (const SoupUri *u1, const SoupUri *u2)
 {
@@ -384,6 +413,12 @@ soup_uri_equal (const SoupUri *u1, const SoupUri *u2)
 	return TRUE;
 }
 
+/**
+ * soup_uri_free:
+ * @uri: a #SoupUri
+ *
+ * Frees @uri.
+ **/
 void
 soup_uri_free (SoupUri *uri)
 {
@@ -483,6 +518,15 @@ soup_uri_decode (char *part)
 	} while (*s++);
 }
 
+/**
+ * soup_uri_uses_default_port:
+ * @uri: a #SoupUri
+ *
+ * Tests if @uri uses the default port for its protocol. (Eg, 80 for
+ * http.)
+ *
+ * Return value: %TRUE or %FALSE
+ **/
 gboolean
 soup_uri_uses_default_port (const SoupUri *uri)
 {