GNOME.org
 

libsoup r1083 - in trunk: . docs/reference libsoup

Author: danw
Date: Sun Feb 10 02:36:40 2008
New Revision: 1083
URL: http://svn.gnome.org/viewvc/libsoup?rev=1083&view=rev

Log:
       * Misc gtk-doc fix-ups


Modified:
   trunk/ChangeLog
   trunk/docs/reference/Makefile.am
   trunk/docs/reference/libsoup-sections.txt
   trunk/libsoup/soup-address.c
   trunk/libsoup/soup-logger.c
   trunk/libsoup/soup-logger.h
   trunk/libsoup/soup-message-body.c
   trunk/libsoup/soup-message-headers.c
   trunk/libsoup/soup-message-headers.h
   trunk/libsoup/soup-message.c
   trunk/libsoup/soup-server.c
   trunk/libsoup/soup-session-sync.c
   trunk/libsoup/soup-session.c
   trunk/libsoup/soup-socket.c
   trunk/libsoup/soup-value-utils.c

Modified: trunk/docs/reference/Makefile.am
==============================================================================
--- trunk/docs/reference/Makefile.am	(original)
+++ trunk/docs/reference/Makefile.am	Sun Feb 10 02:36:40 2008
@@ -34,7 +34,7 @@
 	soup-types.h soup-enum-types.h \
 	soup-auth-basic.h soup-auth-digest.h soup-auth-ntlm.h \
 	soup-connection.h soup-connection-ntlm.h \
-	soup-dns.h soup-auth-manager.h soup-md5-utils.h \
+	soup-dns.h soup-auth-manager.h soup-auth-manager-ntlm.h \
 	soup-message-queue.h soup-path-map.h soup-ssl.h
 
 # Images to copy into HTML directory.

Modified: trunk/docs/reference/libsoup-sections.txt
==============================================================================
--- trunk/docs/reference/libsoup-sections.txt	(original)
+++ trunk/docs/reference/libsoup-sections.txt	Sun Feb 10 02:36:40 2008
@@ -13,9 +13,6 @@
 soup_message_get_http_version
 soup_message_get_uri
 soup_message_set_uri
-SoupMessageFlags
-soup_message_set_flags
-soup_message_get_flags
 <SUBSECTION>
 soup_message_set_status
 soup_message_set_status_full
@@ -24,6 +21,12 @@
 soup_message_add_header_handler
 soup_message_add_status_code_handler
 <SUBSECTION>
+SoupMessageFlags
+soup_message_set_flags
+soup_message_get_flags
+SoupChunkAllocator
+soup_message_set_chunk_allocator
+<SUBSECTION>
 SOUP_MESSAGE_METHOD
 SOUP_MESSAGE_URI
 SOUP_MESSAGE_HTTP_VERSION
@@ -62,6 +65,7 @@
 SOUP_METHOD_DELETE
 SOUP_METHOD_TRACE
 SOUP_METHOD_CONNECT
+<SUBSECTION>
 SOUP_METHOD_PROPFIND
 SOUP_METHOD_PROPPATCH
 SOUP_METHOD_MKCOL
@@ -69,7 +73,6 @@
 SOUP_METHOD_MOVE
 SOUP_METHOD_LOCK
 SOUP_METHOD_UNLOCK
-SOUP_METHOD_PATCH
 </SECTION>
 
 <SECTION>
@@ -85,9 +88,14 @@
 soup_message_headers_remove
 soup_message_headers_clear
 soup_message_headers_get
+<SUBSECTION>
 SoupMessageHeadersForeachFunc
 soup_message_headers_foreach
 <SUBSECTION>
+SoupMessageHeadersIter
+soup_message_headers_iter_init
+soup_message_headers_iter_next
+<SUBSECTION>
 SoupEncoding
 soup_message_headers_get_encoding
 soup_message_headers_set_encoding
@@ -97,6 +105,9 @@
 SoupExpectation
 soup_message_headers_get_expectations
 soup_message_headers_set_expectations
+<SUBSECTION Standard>
+SOUP_TYPE_MESSAGE_HEADERS
+soup_message_headers_get_type
 </SECTION>
 
 <SECTION>
@@ -106,6 +117,8 @@
 SoupMemoryUse
 soup_buffer_new
 soup_buffer_new_subbuffer
+soup_buffer_new_with_owner
+soup_buffer_get_owner
 soup_buffer_copy
 soup_buffer_free
 <SUBSECTION>
@@ -122,6 +135,8 @@
 <SUBSECTION Standard>
 SOUP_TYPE_BUFFER
 soup_buffer_get_type
+SOUP_TYPE_MESSAGE_BODY
+soup_message_body_get_type
 </SECTION>
 
 <SECTION>
@@ -176,6 +191,7 @@
 SOUP_SERVER_SSL_KEY_FILE
 SOUP_SERVER_ASYNC_CONTEXT
 SOUP_SERVER_RAW_PATHS
+SOUP_SERVER_SERVER_HEADER
 <SUBSECTION Standard>
 SOUP_SERVER
 SOUP_IS_SERVER
@@ -200,6 +216,10 @@
 soup_auth_domain_set_filter
 soup_auth_domain_get_realm
 <SUBSECTION>
+SoupAuthDomainGenericAuthCallback
+soup_auth_domain_set_generic_auth_callback
+soup_auth_domain_check_password
+<SUBSECTION>
 soup_auth_domain_covers
 soup_auth_domain_accepts
 soup_auth_domain_challenge
@@ -210,6 +230,10 @@
 SOUP_AUTH_DOMAIN_REMOVE_PATH
 SOUP_AUTH_DOMAIN_FILTER
 SOUP_AUTH_DOMAIN_FILTER_DATA
+SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK
+SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA
+<SUBSECTION Private>
+soup_auth_domain_try_generic_auth_callback
 <SUBSECTION Standard>
 SOUP_AUTH_DOMAIN
 SOUP_IS_AUTH_DOMAIN
@@ -253,8 +277,6 @@
 soup_auth_domain_digest_set_auth_callback
 soup_auth_domain_digest_encode_password
 <SUBSECTION>
-soup_auth_domain_digest_evil_check_password
-<SUBSECTION>
 SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK
 SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA
 <SUBSECTION Standard>
@@ -286,6 +308,12 @@
 soup_address_get_sockaddr
 soup_address_get_physical
 soup_address_get_port
+<SUBSECTION>
+SOUP_ADDRESS_FAMILY
+SOUP_ADDRESS_NAME
+SOUP_ADDRESS_PHYSICAL
+SOUP_ADDRESS_PORT
+SOUP_ADDRESS_SOCKADDR
 <SUBSECTION Standard>
 SOUP_ADDRESS
 SOUP_IS_ADDRESS
@@ -323,6 +351,7 @@
 SOUP_SESSION_SSL_CA_FILE
 SOUP_SESSION_ASYNC_CONTEXT
 SOUP_SESSION_TIMEOUT
+SOUP_SESSION_USER_AGENT
 <SUBSECTION Standard>
 SOUP_IS_SESSION
 SOUP_IS_SESSION_CLASS
@@ -482,6 +511,7 @@
 soup_uri_set_path
 soup_uri_set_query
 soup_uri_set_query_from_form
+soup_uri_set_query_from_fields
 soup_uri_set_fragment
 <SUBSECTION Standard>
 SOUP_TYPE_URI
@@ -498,11 +528,17 @@
 soup_date_new_from_time_t
 soup_date_new_from_now
 soup_date_to_string
+soup_date_to_time_t
 soup_date_free
 <SUBSECTION>
-soup_form_decode_urlencoded
-soup_form_encode_urlencoded
-soup_form_encode_urlencoded_list
+soup_form_decode
+soup_form_encode
+soup_form_encode_datalist
+soup_form_encode_hash
+soup_form_encode_valist
+soup_form_request_new
+soup_form_request_new_from_datalist
+soup_form_request_new_from_hash
 <SUBSECTION>
 soup_headers_parse_request
 soup_headers_parse_response
@@ -525,9 +561,11 @@
 soup_ssl_supported
 <SUBSECTION Private>
 soup_date_copy
-soup_signal_connect_once
 SOUP_TYPE_DATE
 soup_date_get_type
+soup_form_decode_urlencoded
+soup_form_encode_urlencoded
+soup_form_encode_urlencoded_list
 </SECTION>
 
 <SECTION>
@@ -549,6 +587,7 @@
 SOUP_XMLRPC_ERROR
 SoupXMLRPCError
 SOUP_XMLRPC_FAULT
+SoupXMLRPCFault
 <SUBSECTION Private>
 soup_xmlrpc_error_quark
 soup_xmlrpc_fault_quark
@@ -558,14 +597,20 @@
 <FILE>soup-value-utils</FILE>
 <TITLE>GValue Support</TITLE>
 soup_value_hash_new
+soup_value_hash_new_with_vals
 soup_value_hash_insert_value
 soup_value_hash_insert
+soup_value_hash_insert_vals
 soup_value_hash_lookup
+soup_value_hash_lookup_vals
 <SUBSECTION>
 soup_value_array_from_args
 soup_value_array_to_args
+soup_value_array_new
+soup_value_array_new_with_vals
 soup_value_array_insert
 soup_value_array_append
+soup_value_array_append_vals
 soup_value_array_get_nth
 <SUBSECTION>
 SOUP_VALUE_SETV

Modified: trunk/libsoup/soup-address.c
==============================================================================
--- trunk/libsoup/soup-address.c	(original)
+++ trunk/libsoup/soup-address.c	Sun Feb 10 02:36:40 2008
@@ -35,7 +35,7 @@
  * SECTION:soup-address
  * @short_description: DNS support
  *
- * #SoupAddress represents the address of a TCP connection endpoint;
+ * #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.)
  *
@@ -383,6 +383,7 @@
 
 /**
  * SoupAddressFamily:
+ * @SOUP_ADDRESS_FAMILY_INVALID: an invalid %SoupAddress
  * @SOUP_ADDRESS_FAMILY_IPV4: an IPv4 address
  * @SOUP_ADDRESS_FAMILY_IPV6: an IPv6 address
  *
@@ -566,7 +567,7 @@
  * @callback: callback to call with the result
  * @user_data: data for @callback
  *
- * Asynchronously resolves the missing half of @addr. (Its IP address
+ * Asynchronously resolves the missing half of @addr (its IP address
  * if it was created with soup_address_new(), or its hostname if it
  * was created with soup_address_new_from_sockaddr() or
  * soup_address_new_any().)

Modified: trunk/libsoup/soup-logger.c
==============================================================================
--- trunk/libsoup/soup-logger.c	(original)
+++ trunk/libsoup/soup-logger.c	Sun Feb 10 02:36:40 2008
@@ -157,6 +157,8 @@
  * If you need finer control over what message parts are and aren't
  * logged, use soup_logger_set_request_filter() and
  * soup_logger_set_response_filter().
+ *
+ * Returns: a new #SoupLogger
  **/
 SoupLogger *
 soup_logger_new (SoupLoggerLogLevel level, int max_body_size) 

Modified: trunk/libsoup/soup-logger.h
==============================================================================
--- trunk/libsoup/soup-logger.h	(original)
+++ trunk/libsoup/soup-logger.h	Sun Feb 10 02:36:40 2008
@@ -15,9 +15,6 @@
 #define SOUP_IS_LOGGER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((obj), SOUP_TYPE_LOGGER))
 #define SOUP_LOGGER_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), SOUP_TYPE_LOGGER, SoupLoggerClass))
 
-typedef struct SoupLogger      SoupLogger;
-typedef struct SoupLoggerClass SoupLoggerClass;
-
 typedef enum {
 	SOUP_LOGGER_LOG_NONE,
 	SOUP_LOGGER_LOG_MINIMAL,
@@ -25,22 +22,12 @@
 	SOUP_LOGGER_LOG_BODY
 } SoupLoggerLogLevel;
 
-typedef SoupLoggerLogLevel (*SoupLoggerFilter)  (SoupLogger         *logger,
-						 SoupMessage        *msg,
-						 gpointer            user_data);
-
-typedef void               (*SoupLoggerPrinter) (SoupLogger         *logger,
-						 SoupLoggerLogLevel  level,
-						 char                direction,
-						 const char         *data,
-						 gpointer            user_data);
-
-struct SoupLogger {
+typedef struct {
 	GObject parent;
 
-};
+} SoupLogger;
 
-struct SoupLoggerClass {
+typedef struct {
 	GObjectClass parent_class;
 
 	/* Padding for future expansion */
@@ -48,7 +35,17 @@
 	void (*_libsoup_reserved2) (void);
 	void (*_libsoup_reserved3) (void);
 	void (*_libsoup_reserved4) (void);
-};
+} SoupLoggerClass;
+
+typedef SoupLoggerLogLevel (*SoupLoggerFilter)  (SoupLogger         *logger,
+						 SoupMessage        *msg,
+						 gpointer            user_data);
+
+typedef void               (*SoupLoggerPrinter) (SoupLogger         *logger,
+						 SoupLoggerLogLevel  level,
+						 char                direction,
+						 const char         *data,
+						 gpointer            user_data);
 
 GType       soup_logger_get_type    (void);
 

Modified: trunk/libsoup/soup-message-body.c
==============================================================================
--- trunk/libsoup/soup-message-body.c	(original)
+++ trunk/libsoup/soup-message-body.c	Sun Feb 10 02:36:40 2008
@@ -518,6 +518,13 @@
 	return body;
 }
 
+/**
+ * soup_message_body_free:
+ * @body: a #SoupMessageBody
+ *
+ * Frees @body. You will not normally need to use this, as
+ * #SoupMessage frees its associated message bodies automatically.
+ **/
 void
 soup_message_body_free (SoupMessageBody *body)
 {

Modified: trunk/libsoup/soup-message-headers.c
==============================================================================
--- trunk/libsoup/soup-message-headers.c	(original)
+++ trunk/libsoup/soup-message-headers.c	Sun Feb 10 02:36:40 2008
@@ -19,6 +19,15 @@
  * with a request or response.
  **/
 
+/**
+ * SoupMessageHeadersType:
+ * @SOUP_MESSAGE_HEADERS_REQUEST: request headers
+ * @SOUP_MESSAGE_HEADERS_RESPONSE: response headers
+ *
+ * Value passed to soup_message_headers_new() to set certain default
+ * behaviors.
+ **/
+
 typedef void (*SoupHeaderSetter) (SoupMessageHeaders *, const char *);
 static const char *intern_header_name (const char *name, SoupHeaderSetter *setter);
 
@@ -593,6 +602,14 @@
 }
 
 /**
+ * SoupExpectation:
+ * @SOUP_EXPECTATION_CONTINUE: "100-continue"
+ * @SOUP_EXPECTATION_UNRECOGNIZED: any unrecognized expectation
+ *
+ * Represents the parsed value of the "Expect" header.
+ **/
+
+/**
  * soup_message_headers_get_expectations:
  * @hdrs: a #SoupMessageHeaders
  *
@@ -620,8 +637,9 @@
  * large message body (eg, via POST or PUT), and want to give the
  * server a chance to reject the request after seeing just the headers
  * (eg, because it will require authentication before allowing you to
- * post). This saves you from having to transmit the large request
- * body when the server is just going to ignore it anyway.
+ * post, or because you're POSTing to a URL that doesn't exist). This
+ * saves you from having to transmit the large request body when the
+ * server is just going to ignore it anyway.
  **/
 void
 soup_message_headers_set_expectations (SoupMessageHeaders *hdrs,

Modified: trunk/libsoup/soup-message-headers.h
==============================================================================
--- trunk/libsoup/soup-message-headers.h	(original)
+++ trunk/libsoup/soup-message-headers.h	Sun Feb 10 02:36:40 2008
@@ -44,6 +44,7 @@
 						   gpointer            user_data);
 
 typedef struct {
+	/*< private >*/
 	gpointer dummy[3];
 } SoupMessageHeadersIter;
 

Modified: trunk/libsoup/soup-message.c
==============================================================================
--- trunk/libsoup/soup-message.c	(original)
+++ trunk/libsoup/soup-message.c	Sun Feb 10 02:36:40 2008
@@ -21,6 +21,22 @@
  * @short_description: An HTTP request and response.
  * @see_also: #SoupMessageHeaders, #SoupMessageBody
  *
+ * A #SoupMessage represents an HTTP message that is being sent or
+ * received.
+ *
+ * For client-side usage, you would create a #SoupMessage with
+ * soup_message_new() or soup_message_new_from_uri(), set up its
+ * fields appropriate, and send it via a #SoupSession.
+ *
+ * For server-side usage, #SoupServer will create #SoupMessage<!--
+ * -->s automatically for incoming requests, which your application
+ * will receive via handlers.
+ *
+ * Note that libsoup's terminology here does not quite match the HTTP
+ * specification: in RFC 2616, an "HTTP-message" is
+ * <emphasis>either</emphasis> a Request, <emphasis>or</emphasis> a
+ * Response. In libsoup, a #SoupMessage combines both the request and
+ * the response.
  **/
 
 /**

Modified: trunk/libsoup/soup-server.c
==============================================================================
--- trunk/libsoup/soup-server.c	(original)
+++ trunk/libsoup/soup-server.c	Sun Feb 10 02:36:40 2008
@@ -509,6 +509,8 @@
  * @...: value of @optname1, followed by additional property/value pairs
  *
  * Creates a new #SoupServer.
+ *
+ * Return value: a new #SoupServer
  **/
 SoupServer *
 soup_server_new (const char *optname1, ...)

Modified: trunk/libsoup/soup-session-sync.c
==============================================================================
--- trunk/libsoup/soup-session-sync.c	(original)
+++ trunk/libsoup/soup-session-sync.c	Sun Feb 10 02:36:40 2008
@@ -16,10 +16,27 @@
 
 /**
  * SECTION:soup-session-sync
- * @short_description: Soup session for blocking I/O in multithreaded programs.
+ * @short_description: Soup session for blocking I/O in multithreaded
+ * programs.
  *
  * #SoupSessionSync is an implementation of #SoupSession that uses
  * synchronous I/O, intended for use in multi-threaded programs.
+ *
+ * You can use #SoupSessionSync from multiple threads concurrently.
+ * Eg, you can send a #SoupMessage in one thread, and then while
+ * waiting for the response, send another #SoupMessage from another
+ * thread. You can also send a message from one thread and then call
+ * soup_session_cancel_message() on it from any other thread (although
+ * you need to be careful to avoid race conditions, where the message
+ * finishes and is then unreffed by the sending thread just before you
+ * cancel it).
+ *
+ * However, the majority of other types and methods in libsoup are not
+ * MT-safe. In particular, you <emphasis>cannot</emphasis> modify or
+ * examine a #SoupMessage while it is being transmitted by
+ * #SoupSessionSync in another thread. Once a message has been handed
+ * off to #SoupSessionSync, it can only be manipulated from its signal
+ * handler callbacks, until I/O is complete.
  **/
 
 typedef struct {

Modified: trunk/libsoup/soup-session.c
==============================================================================
--- trunk/libsoup/soup-session.c	(original)
+++ trunk/libsoup/soup-session.c	Sun Feb 10 02:36:40 2008
@@ -32,6 +32,26 @@
  * SECTION:soup-session
  * @short_description: Soup session state object
  *
+ * #SoupSession is the object that controls client-side HTTP. A
+ * #SoupSession encapsulates all of the state that libsoup is keeping
+ * on behalf of your program; cached HTTP connections, authentication
+ * information, etc.
+ *
+ * Most applications will only need a single #SoupSession; the primary
+ * reason you might need multiple sessions is if you need to have
+ * multiple independent authentication contexts. (Eg, you are
+ * connecting to a server and authenticating as two different users at
+ * different times; the easiest way to ensure that each #SoupMessage
+ * is sent with the authentication information you intended is to use
+ * one session for the first user, and a second session for the other
+ * user.)
+ *
+ * #SoupSession itself is an abstract class, with two subclasses. If
+ * you are using the glib main loop, you will generally want to use
+ * #SoupSessionAsync, which uses non-blocking I/O and callbacks. On
+ * the other hand, if your application is threaded and you want to do
+ * synchronous I/O in a separate thread from the UI, use
+ * #SoupSessionSync.
  **/
 
 typedef struct {
@@ -954,6 +974,16 @@
 }
 
 /**
+ * SoupSessionCallback:
+ * @session: the session
+ * @msg: the message that has finished
+ * @user_data: the data passed to soup_session_queue_message
+ *
+ * Prototype for the callback passed to soup_session_queue_message(),
+ * qv.
+ **/
+
+/**
  * soup_session_queue_message:
  * @session: a #SoupSession
  * @msg: the message to queue

Modified: trunk/libsoup/soup-socket.c
==============================================================================
--- trunk/libsoup/soup-socket.c	(original)
+++ trunk/libsoup/soup-socket.c	Sun Feb 10 02:36:40 2008
@@ -28,6 +28,10 @@
  * SECTION:soup-socket
  * @short_description: A network socket
  *
+ * #SoupSocket is libsoup's TCP socket type. While it is primarily
+ * intended for internal use, #SoupSocket<!-- -->s are exposed in the
+ * API in various places, and some of their methods (eg,
+ * soup_socket_get_remote_address()) may be useful to applications.
  **/
 
 G_DEFINE_TYPE (SoupSocket, soup_socket, G_TYPE_OBJECT)
@@ -859,6 +863,16 @@
 	return TRUE;
 }
 	
+/**
+ * soup_socket_is_ssl:
+ * @sock: a #SoupSocket
+ *
+ * Tests if @sock is set up to do SSL. Note that this simply means
+ * that the %SOUP_SOCKET_SSL_CREDENTIALS property has been set; it
+ * does not mean that soup_socket_start_ssl() has been called.
+ *
+ * Return value: %TRUE if @sock has SSL credentials set
+ **/
 gboolean
 soup_socket_is_ssl (SoupSocket *sock)
 {

Modified: trunk/libsoup/soup-value-utils.c
==============================================================================
--- trunk/libsoup/soup-value-utils.c	(original)
+++ trunk/libsoup/soup-value-utils.c	Sun Feb 10 02:36:40 2008
@@ -13,6 +13,12 @@
  * SECTION:soup-value-utils
  * @short_description: #GValue utilities
  *
+ * These methods are useful for manipulating #GValue<!-- -->s, and in
+ * particular, arrays and hash tables of #GValue<!-- -->s, in a
+ * slightly nicer way than the standard #GValue API.
+ *
+ * They are written for use with soup-xmlrpc, but they also work with
+ * types not used by XML-RPC.
  **/
 
 /**
@@ -49,6 +55,8 @@
  *
  * Creates a #GHashTable whose keys are strings and whose values
  * are #GValue.
+ *
+ * Return value: a new empty #GHashTable
  **/
 GHashTable *
 soup_value_hash_new (void)
@@ -85,6 +93,8 @@
  * are #GValue, and initializes it with the provided data. As
  * with soup_value_hash_insert(), the keys and values are copied
  * rather than being inserted directly.
+ *
+ * Return value: a new #GHashTable, initialized with the given values
  **/
 GHashTable *
 soup_value_hash_new_with_vals (const char *first_key, ...)
@@ -394,7 +404,7 @@
 }
 
 /**
- * soup_value_array_append_values:
+ * soup_value_array_append_vals:
  * @array: a #GValueArray
  * @first_type: the type of the first value to add
  * @...: the first value to add, followed by other type/value
@@ -460,6 +470,12 @@
 	g_byte_array_free (ba, TRUE);
 }
 
+/**
+ * SOUP_TYPE_BYTE_ARRAY:
+ *
+ * glib does not define a #GType for #GByteArray, so libsoup
+ * defines this one itself.
+ **/
 GType
 soup_byte_array_get_type (void)
 {
@@ -467,7 +483,7 @@
 
 	if (g_once_init_enter (&type_volatile)) {
 		GType type = g_boxed_type_register_static (
-			g_intern_static_string ("GByteArray"),
+			g_intern_static_string ("SoupByteArray"),
 			(GBoxedCopyFunc) soup_byte_array_copy,
 			(GBoxedFreeFunc) soup_byte_array_free);
 		g_once_init_leave (&type_volatile, type);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]