From f0f3d6aeeba584fd795168f93c30de474585da1d Mon Sep 17 00:00:00 2001 From: Dan Winship Date: Wed, 11 Dec 2013 12:13:52 +0100 Subject: Misc docs updates --- .gitignore | 1 + docs/reference/Makefile.am | 3 ++- docs/reference/client-howto.xml | 2 +- docs/reference/libsoup-2.4-sections.txt | 23 +++++++++++++--------- docs/reference/server-howto.xml | 34 ++++++++++++++++----------------- libsoup/soup-content-sniffer.c | 2 +- libsoup/soup-cookie-jar.c | 2 +- libsoup/soup-cookie.c | 22 +++++++-------------- libsoup/soup-message-headers.c | 2 +- libsoup/soup-message.c | 6 ++---- libsoup/soup-proxy-resolver-default.c | 9 ++++++--- libsoup/soup-proxy-uri-resolver.c | 14 +++++++------- libsoup/soup-session.c | 10 +++++----- libsoup/soup-version.c | 19 ++++++++++++++++++ 14 files changed, 84 insertions(+), 65 deletions(-) diff --git a/.gitignore b/.gitignore index 713357b9..293106cf 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,7 @@ config.log config.status configure docs/reference/*.stamp +docs/reference/*.bak docs/reference/html docs/reference/libsoup-2.4-decl-list.txt docs/reference/libsoup-2.4-decl.txt diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index a11ce395..d47693a1 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -44,7 +44,8 @@ IGNORE_HFILES= soup.h soup-enum-types.h \ soup-cache-input-stream.h soup-filter-input-stream.h \ soup-cookie-jar-sqlite.h soup-requester.h soup-tld-private.h \ soup-misc-private.h soup-proxy-uri-resolver.h \ - soup-proxy-resolver-wrapper.h + soup-proxy-resolver-wrapper.h soup-proxy-uri-resolver.h \ + soup-cache-private.h # Images to copy into HTML directory. HTML_IMAGES = diff --git a/docs/reference/client-howto.xml b/docs/reference/client-howto.xml index d4d0f37b..e694cb72 100644 --- a/docs/reference/client-howto.xml +++ b/docs/reference/client-howto.xml @@ -122,7 +122,7 @@ you can specify various additional options: Other properties are also available; see the SoupSession documentation for +linkend="SoupSession">SoupSession documentation for more details. diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt index ca423328..03d35d4b 100644 --- a/docs/reference/libsoup-2.4-sections.txt +++ b/docs/reference/libsoup-2.4-sections.txt @@ -51,8 +51,10 @@ SOUP_MESSAGE_SERVER_SIDE SOUP_MESSAGE_FIRST_PARTY SOUP_MESSAGE_PRIORITY SOUP_MESSAGE_REQUEST_BODY +SOUP_MESSAGE_REQUEST_BODY_DATA SOUP_MESSAGE_REQUEST_HEADERS SOUP_MESSAGE_RESPONSE_BODY +SOUP_MESSAGE_RESPONSE_BODY_DATA SOUP_MESSAGE_RESPONSE_HEADERS SOUP_MESSAGE_TLS_CERTIFICATE SOUP_MESSAGE_TLS_ERRORS @@ -248,6 +250,8 @@ SOUP_SERVER_TLS_CERTIFICATE SOUP_SERVER_ASYNC_CONTEXT SOUP_SERVER_RAW_PATHS SOUP_SERVER_SERVER_HEADER +SOUP_SERVER_HTTP_ALIASES +SOUP_SERVER_HTTPS_ALIASES SOUP_SERVER SOUP_IS_SERVER @@ -439,11 +443,12 @@ SOUP_SESSION_PROXY_URI SOUP_SESSION_PROXY_RESOLVER SOUP_SESSION_MAX_CONNS SOUP_SESSION_MAX_CONNS_PER_HOST -SOUP_SESSION_USE_NTLM -SOUP_SESSION_SSL_CA_FILE -SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE SOUP_SESSION_TLS_DATABASE +SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE +SOUP_SESSION_SSL_CA_FILE +SOUP_SESSION_SSL_STRICT SOUP_SESSION_ASYNC_CONTEXT +SOUP_SESSION_USE_THREAD_CONTEXT SOUP_SESSION_TIMEOUT SOUP_SESSION_IDLE_TIMEOUT SOUP_SESSION_USER_AGENT @@ -452,10 +457,9 @@ SOUP_SESSION_ADD_FEATURE_BY_TYPE SOUP_SESSION_REMOVE_FEATURE_BY_TYPE SOUP_SESSION_ACCEPT_LANGUAGE SOUP_SESSION_ACCEPT_LANGUAGE_AUTO -SOUP_SESSION_SSL_STRICT SOUP_SESSION_HTTP_ALIASES SOUP_SESSION_HTTPS_ALIASES -SOUP_SESSION_USE_THREAD_CONTEXT +SOUP_SESSION_LOCAL_ADDRESS SOUP_IS_SESSION SOUP_IS_SESSION_CLASS @@ -471,6 +475,7 @@ SoupConnection SoupConnectionState SoupMessageQueue SoupMessageQueueItem +SOUP_SESSION_USE_NTLM
@@ -1061,11 +1066,7 @@ SOUP_CACHE_GET_CLASS SoupCacheClass SoupCachePrivate -soup_cache_generate_conditional_request -soup_cache_get_cacheability soup_cache_get_type -soup_cache_has_response -soup_cache_send_response SoupCacheResponse SoupCacheability
@@ -1217,6 +1218,7 @@ SOUP_VERSION_2_38 SOUP_VERSION_2_40 SOUP_VERSION_2_42 SOUP_VERSION_2_44 +SOUP_VERSION_2_46 SOUP_AVAILABLE_IN_2_24 SOUP_AVAILABLE_IN_2_26 @@ -1229,6 +1231,7 @@ SOUP_AVAILABLE_IN_2_38 SOUP_AVAILABLE_IN_2_40 SOUP_AVAILABLE_IN_2_42 SOUP_AVAILABLE_IN_2_44 +SOUP_AVAILABLE_IN_2_46 SOUP_DEPRECATED_IN_2_24 SOUP_DEPRECATED_IN_2_24_FOR SOUP_DEPRECATED_IN_2_26 @@ -1251,6 +1254,8 @@ SOUP_DEPRECATED_IN_2_42 SOUP_DEPRECATED_IN_2_42_FOR SOUP_DEPRECATED_IN_2_44 SOUP_DEPRECATED_IN_2_44_FOR +SOUP_DEPRECATED_IN_2_46 +SOUP_DEPRECATED_IN_2_46_FOR SOUP_ENCODE_VERSION SOUP_VERSION_CUR_STABLE SOUP_VERSION_PREV_STABLE diff --git a/docs/reference/server-howto.xml b/docs/reference/server-howto.xml index 76c19182..05fb0c05 100644 --- a/docs/reference/server-howto.xml +++ b/docs/reference/server-howto.xml @@ -100,7 +100,7 @@ to set a callback to handle certain URI paths. soup_server_add_handler (server, "/foo", server_callback, - data, destroy_notify); + data, destroy_notify); @@ -131,11 +131,11 @@ A handler callback looks something like this: static void server_callback (SoupServer *server, - SoupMessage *msg, - const char *path, - GHashTable *query, - SoupClientContext *client, - gpointer user_data) + SoupMessage *msg, + const char *path, + GHashTable *query, + SoupClientContext *client, + gpointer user_data) { ... } @@ -192,11 +192,11 @@ data available at once. static void server_callback (SoupServer *server, - SoupMessage *msg, - const char *path, - GHashTable *query, - SoupClientContext *client, - gpointer user_data) + SoupMessage *msg, + const char *path, + GHashTable *query, + SoupClientContext *client, + gpointer user_data) { MyServerData *server_data = user_data; const char *mime_type; @@ -219,7 +219,7 @@ server_callback (SoupServer *server, soup_message_set_status (msg, SOUP_STATUS_OK); soup_message_set_response (msg, mime_type, SOUP_MEMORY_COPY, - body->data, body->len); + body->data, body->len); } @@ -264,7 +264,7 @@ is emitted indicating that the previous one was written successfully.) The simple-proxy -example in the tests/ directory gives an example of +example in the examples/ directory gives an example of using chunked encoding. @@ -308,8 +308,8 @@ passed to the server_callback: static gboolean auth_callback (SoupAuthDomain *domain, SoupMessage *msg, - const char *username, const char *password, - gpointer user_data) + const char *username, const char *password, + gpointer user_data) { MyServerData *server_data = user_data; MyUserData *user; @@ -360,8 +360,8 @@ domains. If you want to require authentication for some requests under a certain path, but not all of them (eg, you want to authenticate -PUTs, but not GETs), use a -PUT requests, but not GET +requests), use a SoupAuthDomainFilter. diff --git a/libsoup/soup-content-sniffer.c b/libsoup/soup-content-sniffer.c index e8f69d47..fb2aa090 100644 --- a/libsoup/soup-content-sniffer.c +++ b/libsoup/soup-content-sniffer.c @@ -19,7 +19,7 @@ /** * SECTION:soup-content-sniffer - * @short_description: Content sniffing for #SoupSession + * @short_description: Content sniffing for SoupSession * * A #SoupContentSniffer tries to detect the actual content type of * the files that are being downloaded by looking at some of the data diff --git a/libsoup/soup-cookie-jar.c b/libsoup/soup-cookie-jar.c index 93fd157b..83229705 100644 --- a/libsoup/soup-cookie-jar.c +++ b/libsoup/soup-cookie-jar.c @@ -16,7 +16,7 @@ /** * SECTION:soup-cookie-jar - * @short_description: Automatic cookie handling for #SoupSession + * @short_description: Automatic cookie handling for SoupSession * * A #SoupCookieJar stores #SoupCookies and arrange for them * to be sent with the appropriate #SoupMessages. diff --git a/libsoup/soup-cookie.c b/libsoup/soup-cookie.c index 3f7dcc38..de5efa13 100755 --- a/libsoup/soup-cookie.c +++ b/libsoup/soup-cookie.c @@ -18,17 +18,10 @@ /** * SECTION:soup-cookie * @short_description: HTTP Cookies - * @see_also: #SoupMessage - * - * #SoupCookie implements HTTP cookies, primarily as described by - * the - * original Netscape cookie specification, but with slight - * modifications based on RFC 2109, Microsoft's - * HttpOnly extension attribute, and observed real-world usage - * (and, in particular, based on what Firefox does). + * @see_also: #SoupMessage, #SoupCookieJar + * + * #SoupCookie implements HTTP cookies, as described by RFC 6265. * * To have a #SoupSession handle cookies for your appliction * automatically, use a #SoupCookieJar. @@ -58,10 +51,9 @@ * is a hostname and must match exactly. * * @expires will be non-%NULL if the cookie uses either the original - * "expires" attribute, or the "max-age" attribute specified in RFC - * 2109. If @expires is %NULL, it indicates that neither "expires" nor - * "max-age" was specified, and the cookie expires at the end of the - * session. + * "expires" attribute, or the newer "max-age" attribute. If @expires + * is %NULL, it indicates that neither "expires" nor "max-age" was + * specified, and the cookie expires at the end of the session. * * If @http_only is set, the cookie should not be exposed to untrusted * code (eg, javascript), so as to minimize the danger posed by diff --git a/libsoup/soup-message-headers.c b/libsoup/soup-message-headers.c index 28ecaeda..9c704b49 100644 --- a/libsoup/soup-message-headers.c +++ b/libsoup/soup-message-headers.c @@ -1159,7 +1159,7 @@ soup_message_headers_get_content_range (SoupMessageHeaders *hdrs, * * #SoupServer has built-in handling for range requests, and you do * not normally need to call this function youself. See - * soup_message_headers_get_range() for more details. + * soup_message_headers_get_ranges() for more details. * * * Since: 2.26 diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c index 07967fc2..23fd8b08 100644 --- a/libsoup/soup-message.c +++ b/libsoup/soup-message.c @@ -1780,10 +1780,8 @@ soup_message_set_chunk_allocator (SoupMessage *msg, * This disables the actions of #SoupSessionFeatures with the * given @feature_type (or a subclass of that type) on @msg, so that * @msg is processed as though the feature(s) hadn't been added to the - * session. Eg, passing #SOUP_TYPE_PROXY_URI_RESOLVER for @feature_type - * will disable proxy handling and cause @msg to be sent directly to - * the indicated origin server, regardless of system proxy - * configuration. + * session. Eg, passing #SOUP_TYPE_CONTENT_SNIFFER for @feature_type + * will disable Content-Type sniffing on the message. * * You must call this before queueing @msg on a session; calling it on * a message that has already been queued is undefined. In particular, diff --git a/libsoup/soup-proxy-resolver-default.c b/libsoup/soup-proxy-resolver-default.c index 9149feef..7fd09349 100644 --- a/libsoup/soup-proxy-resolver-default.c +++ b/libsoup/soup-proxy-resolver-default.c @@ -19,16 +19,19 @@ * SECTION:soup-proxy-resolver-default * @short_description: System proxy configuration integration * - * #SoupProxyResolverDefault is a #SoupProxyURIResolver implementation - * that uses the default gio GProxyResolver to resolve proxies. + * #SoupProxyResolverDefault is a SoupProxyURIResolver + * implementation that uses the default gio #GProxyResolver to resolve + * proxies. * - * Deprecated: In libsoup 2.44 and later, you can set the + * In libsoup 2.44 and later, you can set the session's * #SoupSession:proxy-resolver property to the resolver returned by * g_proxy_resolver_get_default() to get the same effect. Note that * for "plain" #SoupSessions (ie, not #SoupSessionAsync or * #SoupSessionSync), this is done for you automatically. * * Since: 2.34 + * + * Deprecated: Use #SoupSession:proxy-resolver */ static void soup_proxy_resolver_default_interface_init (SoupProxyURIResolverInterface *proxy_resolver_interface); diff --git a/libsoup/soup-proxy-uri-resolver.c b/libsoup/soup-proxy-uri-resolver.c index f075a0f7..7971fcb7 100644 --- a/libsoup/soup-proxy-uri-resolver.c +++ b/libsoup/soup-proxy-uri-resolver.c @@ -15,7 +15,7 @@ #include "soup-proxy-uri-resolver.h" #include "soup.h" -/** +/* * SECTION:soup-proxy-uri-resolver * @short_description: Interface for locating HTTP proxies * @@ -40,7 +40,7 @@ soup_proxy_uri_resolver_default_init (SoupProxyURIResolverInterface *iface) { } -/** +/* * SoupProxyURIResolverCallback: * @resolver: the #SoupProxyURIResolver * @status: a #SoupStatus @@ -48,9 +48,9 @@ soup_proxy_uri_resolver_default_init (SoupProxyURIResolverInterface *iface) * @user_data: data passed to soup_proxy_uri_resolver_get_proxy_uri_async() * * Callback for soup_proxy_uri_resolver_get_proxy_uri_async() - **/ + */ -/** +/* * soup_proxy_uri_resolver_get_proxy_uri_async: * @proxy_uri_resolver: the #SoupProxyURIResolver * @uri: the #SoupURI you want a proxy for @@ -66,7 +66,7 @@ soup_proxy_uri_resolver_default_init (SoupProxyURIResolverInterface *iface) * * Deprecated: #SoupProxyURIResolver is deprecated in favor of * #GProxyResolver - **/ + */ void soup_proxy_uri_resolver_get_proxy_uri_async (SoupProxyURIResolver *proxy_uri_resolver, SoupURI *uri, @@ -81,7 +81,7 @@ soup_proxy_uri_resolver_get_proxy_uri_async (SoupProxyURIResolver *proxy_uri_re callback, user_data); } -/** +/* * soup_proxy_uri_resolver_get_proxy_uri_sync: * @proxy_uri_resolver: the #SoupProxyURIResolver * @uri: the #SoupURI you want a proxy for @@ -99,7 +99,7 @@ soup_proxy_uri_resolver_get_proxy_uri_async (SoupProxyURIResolver *proxy_uri_re * * Deprecated: #SoupProxyURIResolver is deprecated in favor of * #GProxyResolver - **/ + */ guint soup_proxy_uri_resolver_get_proxy_uri_sync (SoupProxyURIResolver *proxy_uri_resolver, SoupURI *uri, diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c index f2e643f3..b3081f14 100644 --- a/libsoup/soup-session.c +++ b/libsoup/soup-session.c @@ -3099,9 +3099,9 @@ soup_session_class_init (SoupSessionClass *session_class) * A proxy to use for all http and https requests in this * session. Setting this will clear the * #SoupSession:proxy-resolver property, and remove any - * #SoupProxyURIResolver features that have been added to the - * session. Setting this property will also cancel all - * currently pending messages. + * SoupProxyURIResolver features that have been + * added to the session. Setting this property will also + * cancel all currently pending messages. * * Note that #SoupSession will normally handle looking up the * user's proxy settings for you; you should only use @@ -3131,8 +3131,8 @@ soup_session_class_init (SoupSessionClass *session_class) * * A #GProxyResolver to use with this session. Setting this * will clear the #SoupSession:proxy-uri property, and remove - * any #SoupProxyURIResolver features that have been added to - * the session. + * any SoupProxyURIResolver features that have + * been added to the session. * * By default, in a plain #SoupSession, this is set to the * default #GProxyResolver, but you can set it to %NULL if you diff --git a/libsoup/soup-version.c b/libsoup/soup-version.c index 8a0fa929..31e7262d 100644 --- a/libsoup/soup-version.c +++ b/libsoup/soup-version.c @@ -286,3 +286,22 @@ soup_check_version (guint major, * Since: 2.42 */ +/** + * SOUP_VERSION_2_44: + * + * A macro that evaluates to the 2.44 version of libsoup, in a format + * that can be used by %SOUP_VERSION_MIN_REQUIRED and + * %SOUP_VERSION_MAX_ALLOWED. + * + * Since: 2.44 + */ + +/** + * SOUP_VERSION_2_46: + * + * A macro that evaluates to the 2.46 version of libsoup, in a format + * that can be used by %SOUP_VERSION_MIN_REQUIRED and + * %SOUP_VERSION_MAX_ALLOWED. + * + * Since: 2.46 + */ -- cgit v1.2.1