doc fixups

	* libsoup/soup-cookie-jar.c:
	* libsoup/soup-cookie.c:
	* libsoup/soup-cookie.h:
	* libsoup/soup-headers.c:
	* libsoup/soup-logger.c:
	* libsoup/soup-session-feature.c:
	* libsoup/soup-session-feature.h:
	* libsoup/soup-session.c: doc fixups

	* docs/reference/libsoup-2.4-docs.sgml:
	* docs/reference/libsoup-2.4-sections.txt:
	* docs/reference/libsoup-2.4.types: Add missing bits

svn path=/trunk/; revision=1170

12 files changed, 200 insertions, 31 deletions

diff --git a/ChangeLog b/ChangeLog
index ae81b4e8..d462667e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2008-10-01  Dan Winship  <danw@gnome.org>
+
+	* libsoup/soup-cookie-jar.c:
+	* libsoup/soup-cookie.c:
+	* libsoup/soup-cookie.h:
+	* libsoup/soup-headers.c:
+	* libsoup/soup-logger.c:
+	* libsoup/soup-session-feature.c:
+	* libsoup/soup-session-feature.h:
+	* libsoup/soup-session.c: doc fixups
+
+	* docs/reference/libsoup-2.4-docs.sgml:
+	* docs/reference/libsoup-2.4-sections.txt:
+	* docs/reference/libsoup-2.4.types: Add missing bits
+
 2008-09-30  Dan Winship  <danw@gnome.org>
 
 	* libsoup/soup-xmlrpc.c (parse_value):
diff --git a/docs/reference/libsoup-2.4-docs.sgml b/docs/reference/libsoup-2.4-docs.sgml
index fd1d2bdf..d4c3239f 100644
--- a/docs/reference/libsoup-2.4-docs.sgml
+++ b/docs/reference/libsoup-2.4-docs.sgml
@@ -20,6 +20,8 @@
     <xi:include href="xml/soup-auth-domain.xml"/>
     <xi:include href="xml/soup-auth-domain-basic.xml"/>
     <xi:include href="xml/soup-auth-domain-digest.xml"/>
+    <xi:include href="xml/soup-cookie.xml"/>
+    <xi:include href="xml/soup-cookie-jar.xml"/>
     <xi:include href="xml/soup-logger.xml"/>
     <xi:include href="xml/soup-message.xml"/>
     <xi:include href="xml/soup-message-headers.xml"/>
diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt
index 3d1f615e..035bcf03 100644
--- a/docs/reference/libsoup-2.4-sections.txt
+++ b/docs/reference/libsoup-2.4-sections.txt
@@ -352,6 +352,12 @@ soup_session_unpause_message
 <SUBSECTION>
 soup_session_get_async_context
 <SUBSECTION>
+SoupSessionFeature
+soup_session_add_feature
+soup_session_add_feature_by_type
+soup_session_remove_feature
+soup_session_remove_feature_by_type
+<SUBSECTION>
 SOUP_SESSION_PROXY_URI
 SOUP_SESSION_MAX_CONNS
 SOUP_SESSION_MAX_CONNS_PER_HOST
@@ -361,6 +367,9 @@ SOUP_SESSION_ASYNC_CONTEXT
 SOUP_SESSION_TIMEOUT
 SOUP_SESSION_IDLE_TIMEOUT
 SOUP_SESSION_USER_AGENT
+SOUP_SESSION_ADD_FEATURE
+SOUP_SESSION_ADD_FEATURE_BY_TYPE
+SOUP_SESSION_REMOVE_FEATURE_BY_TYPE
 <SUBSECTION Standard>
 SOUP_IS_SESSION
 SOUP_IS_SESSION_CLASS
@@ -370,6 +379,17 @@ SOUP_SESSION_GET_CLASS
 SOUP_TYPE_SESSION
 SoupSessionClass
 soup_session_get_type
+<SUBSECTION Private>
+soup_session_feature_attach
+soup_session_feature_detach
+SoupSessionFeatureInterface
+soup_session_feature_get_type
+SOUP_SESSION_FEATURE
+SOUP_SESSION_FEATURE_CLASS
+SOUP_SESSION_FEATURE_GET_CLASS
+SOUP_IS_SESSION_FEATURE
+SOUP_IS_SESSION_FEATURE_CLASS
+SOUP_TYPE_SESSION_FEATURE
 </SECTION>
 
 <SECTION>
@@ -511,6 +531,7 @@ soup_uri_normalize
 SOUP_URI_SCHEME_HTTP
 SOUP_URI_SCHEME_HTTPS
 soup_uri_uses_default_port
+SOUP_URI_VALID_FOR_HTTP
 <SUBSECTION>
 soup_uri_set_scheme
 soup_uri_set_user
@@ -538,6 +559,8 @@ soup_date_new_from_time_t
 soup_date_new_from_now
 soup_date_to_string
 soup_date_to_time_t
+soup_date_to_timeval
+soup_date_is_past
 soup_date_free
 <SUBSECTION>
 soup_form_decode
@@ -558,6 +581,7 @@ soup_header_parse_quality_list
 soup_header_free_list
 soup_header_contains
 soup_header_parse_param_list
+soup_header_parse_semi_param_list
 soup_header_free_param_list
 <SUBSECTION>
 soup_str_case_equal
@@ -656,3 +680,56 @@ SOUP_LOGGER_CLASS
 SOUP_LOGGER_GET_CLASS
 SOUP_TYPE_LOGGER
 </SECTION>
+
+<SECTION>
+<FILE>soup-cookie</FILE>
+<TITLE>SoupCookie</TITLE>
+SoupCookie
+soup_cookie_new
+soup_cookie_parse
+soup_cookie_free
+<SUBSECTION>
+soup_cookie_set_name
+soup_cookie_set_value
+soup_cookie_set_domain
+soup_cookie_set_path
+soup_cookie_set_max_age
+SOUP_COOKIE_MAX_AGE_ONE_HOUR
+SOUP_COOKIE_MAX_AGE_ONE_DAY
+SOUP_COOKIE_MAX_AGE_ONE_WEEK
+SOUP_COOKIE_MAX_AGE_ONE_YEAR
+soup_cookie_set_expires
+soup_cookie_set_secure
+soup_cookie_set_http_only
+<SUBSECTION>
+soup_cookie_applies_to_uri
+<SUBSECTION>
+soup_cookie_to_cookie_header
+soup_cookie_to_set_cookie_header
+<SUBSECTION>
+soup_cookies_from_request
+soup_cookies_from_response
+soup_cookies_to_request
+soup_cookies_to_response
+soup_cookies_to_cookie_header
+soup_cookies_free
+</SECTION>
+
+<SECTION>
+<FILE>soup-cookie-jar</FILE>
+<TITLE>SoupCookieJar</TITLE>
+SoupCookieJar
+soup_cookie_jar_new
+soup_cookie_jar_save
+soup_cookie_jar_get_cookies
+soup_cookie_jar_set_cookie
+<SUBSECTION Standard>
+SoupCookieJarClass
+SOUP_COOKIE_JAR
+SOUP_COOKIE_JAR_CLASS
+SOUP_COOKIE_JAR_GET_CLASS
+SOUP_IS_COOKIE_JAR
+SOUP_IS_COOKIE_JAR_CLASS
+SOUP_TYPE_COOKIE_JAR
+soup_cookie_jar_get_type
+</SECTION>
diff --git a/docs/reference/libsoup-2.4.types b/docs/reference/libsoup-2.4.types
index 9effee14..a342980a 100644
--- a/docs/reference/libsoup-2.4.types
+++ b/docs/reference/libsoup-2.4.types
@@ -5,10 +5,13 @@ soup_auth_get_type
 soup_auth_domain_get_type
 soup_auth_domain_basic_get_type
 soup_auth_domain_digest_get_type
+soup_cookie_jar_get_type
+soup_logger_get_type
 soup_message_get_type
 soup_server_get_type
 soup_session_get_type
 soup_session_sync_get_type
 soup_session_async_get_type
+soup_session_feature_get_type
 soup_socket_get_type
 
diff --git a/libsoup/soup-cookie-jar.c b/libsoup/soup-cookie-jar.c
index fecd2c1e..9b717c5a 100644
--- a/libsoup/soup-cookie-jar.c
+++ b/libsoup/soup-cookie-jar.c
@@ -21,7 +21,7 @@
 
 /**
  * SECTION:soup-cookie-jar
- * @short_description: 
+ * @short_description: Automatic cookie handling for #SoupSession
  *
  * A #SoupCookieJar stores #SoupCookie<!-- -->s and arrange for them
  * to be sent with the appropriate #SoupMessage<!-- -->s.
diff --git a/libsoup/soup-cookie.c b/libsoup/soup-cookie.c
index e6f364de..d095eda5 100644
--- a/libsoup/soup-cookie.c
+++ b/libsoup/soup-cookie.c
@@ -34,6 +34,9 @@
  * url="http://msdn2.microsoft.com/en-us/library/ms533046.aspx">Microsoft's
  * HttpOnly extension attribute</ulink>, and observed real-world usage
  * (and, in particular, based on what Firefox does).
+ *
+ * To have a #SoupSession handle cookies for your appliction
+ * automatically, use a #SoupCookieJar.
  **/
 
 /**
@@ -391,13 +394,13 @@ soup_cookie_new (const char *name, const char *value,
 
 /**
  * soup_cookie_parse:
- * @cookie: a cookie string (eg, the value of a Set-Cookie header)
+ * @header: a cookie string (eg, the value of a Set-Cookie header)
  * @origin: origin of the cookie, or %NULL
  *
- * Parses @cookie and returns a #SoupCookie. (If @cookie contains
+ * Parses @header and returns a #SoupCookie. (If @header contains
  * multiple cookies, only the first one will be parsed.)
  *
- * If @cookie does not have "path" or "domain" attributes, they will
+ * If @header does not have "path" or "domain" attributes, they will
  * be defaulted from @origin. If @origin is %NULL, path will default
  * to "/", but domain will be left as %NULL. Note that this is not a
  * valid state for a #SoupCookie, and you will need to fill in some
@@ -504,6 +507,31 @@ soup_cookie_set_max_age (SoupCookie *cookie, int max_age)
 }
 
 /**
+ * SOUP_COOKIE_MAX_AGE_ONE_HOUR:
+ *
+ * A constant corresponding to 1 hour, for use with soup_cookie_new()
+ * and soup_cookie_set_max_age().
+ **/
+/**
+ * SOUP_COOKIE_MAX_AGE_ONE_DAY:
+ *
+ * A constant corresponding to 1 day, for use with soup_cookie_new()
+ * and soup_cookie_set_max_age().
+ **/
+/**
+ * SOUP_COOKIE_MAX_AGE_ONE_WEEK:
+ *
+ * A constant corresponding to 1 week, for use with soup_cookie_new()
+ * and soup_cookie_set_max_age().
+ **/
+/**
+ * SOUP_COOKIE_MAX_AGE_ONE_YEAR:
+ *
+ * A constant corresponding to 1 year, for use with soup_cookie_new()
+ * and soup_cookie_set_max_age().
+ **/
+
+/**
  * soup_cookie_set_expires:
  * @cookie: a #SoupCookie
  * @expires: the new expiration time, or %NULL
@@ -656,7 +684,7 @@ soup_cookie_free (SoupCookie *cookie)
  *
  * Parses @msg's Set-Cookie response headers and returns a #GSList of
  * #SoupCookie<!-- -->s. Cookies that do not specify "path" or
- * "domain" attributes will have their values defaulted from @origin.
+ * "domain" attributes will have their values defaulted from @msg.
  *
  * Return value: a #GSList of #SoupCookie<!-- -->s, which can be freed
  * with soup_cookies_free().
diff --git a/libsoup/soup-cookie.h b/libsoup/soup-cookie.h
index 84b46029..2c1bad46 100644
--- a/libsoup/soup-cookie.h
+++ b/libsoup/soup-cookie.h
@@ -48,7 +48,7 @@ void        soup_cookie_set_expires             (SoupCookie  *cookie,
 void        soup_cookie_set_secure              (SoupCookie  *cookie,
 						 gboolean     secure);
 void        soup_cookie_set_http_only           (SoupCookie  *cookie,
-						 gboolean     secure);
+						 gboolean     http_only);
 
 char       *soup_cookie_to_set_cookie_header    (SoupCookie  *cookie);
 char       *soup_cookie_to_cookie_header        (SoupCookie  *cookie);
diff --git a/libsoup/soup-headers.c b/libsoup/soup-headers.c
index 662404ba..42ba8c4f 100644
--- a/libsoup/soup-headers.c
+++ b/libsoup/soup-headers.c
@@ -648,14 +648,14 @@ parse_param_list (const char *header, char delim)
  * soup_header_parse_param_list:
  * @header: a header value
  *
- * Parses a header which is a comma-delimited list of something like
- *
- *   token [ "=" ( token | quoted-string ) ]
+ * Parses a header which is a comma-delimited list of something like:
+ * <literal>token [ "=" ( token | quoted-string ) ]</literal>.
  *
  * Tokens that don't have an associated value will still be added to
  * the resulting hash table, but with a %NULL value.
  * 
- * Return value: a #GHashTable of list elements.
+ * Return value: a #GHashTable of list elements, which can be freed
+ * with soup_header_free_param_list().
  **/
 GHashTable *
 soup_header_parse_param_list (const char *header)
@@ -668,14 +668,13 @@ soup_header_parse_param_list (const char *header)
  * @header: a header value
  *
  * Parses a header which is a semicolon-delimited list of something
- * like
- *
- *   token [ "=" ( token | quoted-string ) ]
+ * like: <literal>token [ "=" ( token | quoted-string ) ]</literal>.
  *
  * Tokens that don't have an associated value will still be added to
  * the resulting hash table, but with a %NULL value.
  * 
- * Return value: a #GHashTable of list elements.
+ * Return value: a #GHashTable of list elements, which can be freed
+ * with soup_header_free_param_list().
  **/
 GHashTable *
 soup_header_parse_semi_param_list (const char *header)
@@ -686,6 +685,7 @@ soup_header_parse_semi_param_list (const char *header)
 /**
  * soup_header_free_param_list:
  * @param_list: a #GHashTable returned from soup_header_parse_param_list()
+ * or soup_header_parse_semi_param_list()
  *
  * Frees @param_list.
  **/
diff --git a/libsoup/soup-logger.c b/libsoup/soup-logger.c
index 34c63606..37b9fec9 100644
--- a/libsoup/soup-logger.c
+++ b/libsoup/soup-logger.c
@@ -32,7 +32,7 @@
  * optionally configure it with soup_logger_set_request_filter(),
  * soup_logger_set_response_filter(), and soup_logger_set_printer(),
  * and then attach it to a session (or multiple sessions) with
- * soup_logger_attach().
+ * soup_session_add_feature().
  *
  * By default, the debugging output is sent to %stdout, and looks
  * something like:
diff --git a/libsoup/soup-session-feature.c b/libsoup/soup-session-feature.c
index a2abb0b8..71526de2 100644
--- a/libsoup/soup-session-feature.c
+++ b/libsoup/soup-session-feature.c
@@ -11,6 +11,26 @@
 
 #include "soup-session-feature.h"
 
+/**
+ * SECTION:soup-session-feature
+ * @short_description: Interface for miscellaneous session features
+ *
+ * #SoupSessionFeature is the interface used by classes that extend
+ * the functionality of a #SoupSession. Some features like HTTP
+ * authentication handling are implemented internally via
+ * #SoupSessionFeature<!-- -->s. Other features can be added to the session
+ * by the application. (Eg, #SoupLogger, #SoupCookieJar.)
+ *
+ * See soup_session_add_feature(), etc, to add a feature to a session.
+ **/
+
+/**
+ * SoupSessionFeature:
+ *
+ * The interface implemented by objects that implement features for
+ * #SoupSession.
+ **/
+
 static void soup_session_feature_interface_init (SoupSessionFeatureInterface *interface);
 
 static void attach (SoupSessionFeature *feature, SoupSession *session);
@@ -93,13 +113,6 @@ attach (SoupSessionFeature *feature, SoupSession *session)
 	}
 }
 
-/**
- * soup_session_feature_attach:
- * @feature: a #SoupSessionFeature
- * @session: a #SoupSession
- *
- * Adds @feature to @session.
- **/
 void
 soup_session_feature_attach (SoupSessionFeature *feature,
 			     SoupSession        *session)
@@ -119,15 +132,6 @@ detach (SoupSessionFeature *feature, SoupSession *session)
 	g_object_unref (feature);
 }
 
-/**
- * soup_session_feature_detach:
- * @feature: a #SoupSessionFeature
- * @session: a #SoupSession
- *
- * Removes @feature from @session.
- *
- * Return value: success or failure
- **/
 void
 soup_session_feature_detach (SoupSessionFeature *feature,
 			     SoupSession        *session)
diff --git a/libsoup/soup-session-feature.h b/libsoup/soup-session-feature.h
index 0bdf078e..f64e3156 100644
--- a/libsoup/soup-session-feature.h
+++ b/libsoup/soup-session-feature.h
@@ -17,6 +17,9 @@ G_BEGIN_DECLS
 #define SOUP_IS_SESSION_FEATURE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), SOUP_TYPE_SESSION_FEATURE))
 #define SOUP_SESSION_FEATURE_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), SOUP_TYPE_SESSION_FEATURE, SoupSessionFeatureInterface))
 
+/* dummy struct for gtk-doc */
+struct _SoupSessionFeature {};
+
 typedef struct {
 	GTypeInterface parent;
 
diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c
index 41134cf4..3107ad16 100644
--- a/libsoup/soup-session.c
+++ b/libsoup/soup-session.c
@@ -1340,6 +1340,15 @@ soup_session_abort (SoupSession *session)
 	g_slist_free (conns);
 }
 
+/**
+ * soup_session_add_feature:
+ * @session: a #SoupSession
+ * @feature: an object that implements #SoupSessionFeature
+ *
+ * Adds @feature's functionality to @session. You can also add a
+ * feature to the session at construct time by using the
+ * %SOUP_SESSION_ADD_FEATURE property.
+ **/
 void
 soup_session_add_feature (SoupSession *session, SoupSessionFeature *feature)
 {
@@ -1353,6 +1362,17 @@ soup_session_add_feature (SoupSession *session, SoupSessionFeature *feature)
 	soup_session_feature_attach (feature, session);
 }
 
+/**
+ * soup_session_add_feature_by_type:
+ * @session: a #SoupSession
+ * @feature_type: the #GType of a class that implements #SoupSessionFeature
+ *
+ * Creates a new feature of type @feature_type and adds it to
+ * @session. You can use this instead of soup_session_add_feature() in
+ * the case wher you don't need to customize the new feature in any
+ * way. You can also add a feature to the session at construct time by
+ * using the %SOUP_SESSION_ADD_FEATURE_BY_TYPE property.
+ **/
 void
 soup_session_add_feature_by_type (SoupSession *session, GType feature_type)
 {
@@ -1366,6 +1386,13 @@ soup_session_add_feature_by_type (SoupSession *session, GType feature_type)
 	g_object_unref (feature);
 }
 
+/**
+ * soup_session_remove_feature:
+ * @session: a #SoupSession
+ * @feature: a feature that has previously been added to @session
+ *
+ * Removes @feature's functionality from @session.
+ **/
 void
 soup_session_remove_feature (SoupSession *session, SoupSessionFeature *feature)
 {
@@ -1381,6 +1408,16 @@ soup_session_remove_feature (SoupSession *session, SoupSessionFeature *feature)
 	}
 }
 
+/**
+ * soup_session_remove_feature_by_type:
+ * @session: a #SoupSession
+ * @feature_type: the #GType of a class that implements #SoupSessionFeature
+ *
+ * Removes all features of type @feature_type (or any subclass of
+ * @feature_type) from @session. You can also remove standard features
+ * from the session at construct time by using the
+ * %SOUP_SESSION_REMOVE_FEATURE_BY_TYPE property.
+ **/
 void
 soup_session_remove_feature_by_type (SoupSession *session, GType feature_type)
 {