From 360a32a81904ce6f662de420cfa57961f2726d14 Mon Sep 17 00:00:00 2001 From: Dan Winship Date: Fri, 28 Dec 2012 10:32:30 -0500 Subject: [PATCH] docs: more fixes --- docs/reference/Makefile.am | 2 +- docs/reference/build-howto.xml | 73 +++++++++++++++++---------------- docs/reference/libsoup-2.4-sections.txt | 1 - libsoup/soup-cache.c | 7 ++++ libsoup/soup-proxy-resolver-default.c | 7 ++-- libsoup/soup-proxy-uri-resolver.c | 12 ++++++ libsoup/soup-request-data.c | 7 ++++ libsoup/soup-request-file.c | 8 ++++ libsoup/soup-request-http.c | 12 ++++++ libsoup/soup-session.h | 2 +- libsoup/soup-value-utils.c | 2 +- 11 files changed, 90 insertions(+), 43 deletions(-) diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 9dbadb3..019746b 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -13,7 +13,7 @@ DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml DOC_SOURCE_DIR=../../libsoup # Extra options to supply to gtkdoc-scan. -SCAN_OPTIONS=--rebuild-types +SCAN_OPTIONS=--rebuild-types --ignore-decorators='SOUP_DEPRECATED\w*\s*\([^)]*\)|SOUP_DEPRECATED\w*|SOUP_AVAILABLE\w*' # Extra options to supply to gtkdoc-scangobj. SCANGOBJ_OPTIONS= diff --git a/docs/reference/build-howto.xml b/docs/reference/build-howto.xml index 975dfd5..bec9a45 100644 --- a/docs/reference/build-howto.xml +++ b/docs/reference/build-howto.xml @@ -35,41 +35,52 @@ that first appeared in version 2.4") and is essentially just part of the package name. + + + +API Availability and Deprecation Warnings + -If you are using any of the GNOME-specific features of -libsoup (such as automatic proxy -configuration), you must require -"libsoup-gnome-2.4" instead: +If you want to restrict your program to a particular +libsoup version or range of versions, you +can define SOUP_VERSION_MIN_REQUIRED +and/or SOUP_VERSION_MAX_ALLOWED. +Eg: -PKG_CHECK_MODULES(LIBSOUP, [libsoup-gnome-2.4 >= 2.26]) -AC_SUBST(LIBSOUP_CFLAGS) -AC_SUBST(LIBSOUP_LIBS) +LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_2_36" +LIBSOUP_CFLAGS="$LIBSOUP_CFLAGS -DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_2_40" -You can also make libsoup-gnome an optional -dependency: +The SOUP_VERSION_MIN_REQUIRED declaration states +that the code is not expected to compile on versions of +libsoup older than the indicated version +(here, 2.36), and so the compiler should print warnings if the code +uses functions that were deprecated as of that release. - -PKG_CHECK_MODULES(LIBSOUP_GNOME, - [libsoup-gnome-2.4 >= 2.26], - [LIBSOUP_CFLAGS="$LIBSOUP_GNOME_CFLAGS" - LIBSOUP_LIBS="$LIBSOUP_GNOME_LIBS" - AC_DEFINE(HAVE_LIBSOUP_GNOME, 1, [Have libsoup-gnome])], - [PKG_CHECK_MODULES(LIBSOUP, [libsoup-2.4 >= 2.26])]) -AC_SUBST(LIBSOUP_CFLAGS) -AC_SUBST(LIBSOUP_LIBS) - + +The SOUP_VERSION_MAX_ALLOWED declaration states +that the code is expected to compile on versions +of libsoup up to the indicated version +(here, 2.40), and so, when compiling the program against a newer +version than that, the compiler should print warnings if the code uses +functions that did not yet exist in the max-allowed release. + -This will allow the application to be built with either plain -libsoup or with -libsoup-gnome, and it will define the C -preprocessor symbol HAVE_LIBSOUP_GNOME if -libsoup-gnome features are available. +You can use SOUP_CHECK_VERSION +to check the version of libsoup at compile time, to compile different +code for different libsoup versions. (If +you are setting SOUP_VERSION_MIN_REQUIRED and +SOUP_VERSION_MAX_ALLOWED to different versions, as +in the example above, then you almost certainly need to be doing +this.) @@ -86,18 +97,8 @@ Code using libsoup should do: -or, for libsoup-gnome: - - - -#include <libsoup/soup-gnome.h> - - - -Including individual headers besides the two main header files is not -recommended. You may include both soup.h and -soup-gnome.h (though this is not required; the -latter automatically includes the former). +Including individual headers rather than soup.h is not +recommended. diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt index 23f55c0..db45167 100644 --- a/docs/reference/libsoup-2.4-sections.txt +++ b/docs/reference/libsoup-2.4-sections.txt @@ -451,7 +451,6 @@ SOUP_SESSION_GET_CLASS SOUP_TYPE_SESSION SoupSessionClass soup_session_get_type -soup_request_error_get_type soup_request_error_quark SoupConnection diff --git a/libsoup/soup-cache.c b/libsoup/soup-cache.c index 6df1665..5569d6b 100644 --- a/libsoup/soup-cache.c +++ b/libsoup/soup-cache.c @@ -39,6 +39,13 @@ #include "soup-message-private.h" #include "soup.h" +/** + * SECTION:soup-cache + * @short_description: Caching support + * + * #SoupCache implements a file-based cache for HTTP resources. + */ + static SoupSessionFeatureInterface *soup_cache_default_feature_interface; static void soup_cache_session_feature_init (SoupSessionFeatureInterface *feature_interface, gpointer interface_data); diff --git a/libsoup/soup-proxy-resolver-default.c b/libsoup/soup-proxy-resolver-default.c index 76e9ff6..0fc8780 100644 --- a/libsoup/soup-proxy-resolver-default.c +++ b/libsoup/soup-proxy-resolver-default.c @@ -13,10 +13,11 @@ #include "soup.h" /** - * SoupProxyResolverDefault: + * SECTION:soup-proxy-resolver-default + * @short_description: System proxy configuration integration * - * 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. * * Since: 2.34 */ diff --git a/libsoup/soup-proxy-uri-resolver.c b/libsoup/soup-proxy-uri-resolver.c index 8aecec4..65f65d4 100644 --- a/libsoup/soup-proxy-uri-resolver.c +++ b/libsoup/soup-proxy-uri-resolver.c @@ -12,6 +12,18 @@ #include "soup-proxy-uri-resolver.h" #include "soup.h" +/** + * SECTION:soup-proxy-uri-resolver + * @short_description: Interface for locating HTTP proxies + * + * #SoupProxyURIResolver is an interface for finding appropriate HTTP + * proxies to use. + * + * You are not likely to have to implement this interface on your own; + * instead, you should usually just be able to use + * #SoupProxyResolverDefault. + */ + G_DEFINE_INTERFACE (SoupProxyURIResolver, soup_proxy_uri_resolver, G_TYPE_OBJECT) static void diff --git a/libsoup/soup-request-data.c b/libsoup/soup-request-data.c index 0ff30c9..66836a5 100644 --- a/libsoup/soup-request-data.c +++ b/libsoup/soup-request-data.c @@ -31,6 +31,13 @@ #include "soup.h" #include "soup-misc-private.h" +/** + * SECTION:soup-request-data + * @short_description: SoupRequest support for "data" URIs + * + * #SoupRequestData implements #SoupRequest for "data" URIs. + */ + G_DEFINE_TYPE (SoupRequestData, soup_request_data, SOUP_TYPE_REQUEST) struct _SoupRequestDataPrivate { diff --git a/libsoup/soup-request-file.c b/libsoup/soup-request-file.c index a71827b..49b741d 100644 --- a/libsoup/soup-request-file.c +++ b/libsoup/soup-request-file.c @@ -30,6 +30,14 @@ #include "soup-directory-input-stream.h" #include "soup-requester.h" +/** + * SECTION:soup-request-file + * @short_description: SoupRequest support for "file" and "resource" URIs + * + * #SoupRequestFile implements #SoupRequest for "file" and "resource" + * URIs. + */ + G_DEFINE_TYPE (SoupRequestFile, soup_request_file, SOUP_TYPE_REQUEST) struct _SoupRequestFilePrivate { diff --git a/libsoup/soup-request-http.c b/libsoup/soup-request-http.c index 871ca0e..e932217 100644 --- a/libsoup/soup-request-http.c +++ b/libsoup/soup-request-http.c @@ -32,6 +32,18 @@ #include "soup-message-private.h" #include "soup-session-private.h" +/** + * SECTION:soup-request-http + * @short_description: SoupRequest support for "http" and "https" URIs + * + * #SoupRequestHTTP implements #SoupRequest for "http" and "https" + * URIs. + * + * To do more complicated HTTP operations using the #SoupRequest APIs, + * call soup_request_http_get_message() to get the request's + * #SoupMessage. + */ + G_DEFINE_TYPE (SoupRequestHTTP, soup_request_http, SOUP_TYPE_REQUEST) /** diff --git a/libsoup/soup-session.h b/libsoup/soup-session.h index ca5060e..b64fcae 100644 --- a/libsoup/soup-session.h +++ b/libsoup/soup-session.h @@ -103,7 +103,7 @@ void soup_session_cancel_message (SoupSession *session, guint status_code); void soup_session_abort (SoupSession *session); -SOUP_AVAILABLE_IN_2_30 +/* SOUP_AVAILABLE_IN_2_30 -- this trips up gtkdoc-scan */ SOUP_DEPRECATED_IN_2_38_FOR (soup_session_prefetch_dns) void soup_session_prepare_for_uri (SoupSession *session, SoupURI *uri); diff --git a/libsoup/soup-value-utils.c b/libsoup/soup-value-utils.c index b929544..e1f7c92 100644 --- a/libsoup/soup-value-utils.c +++ b/libsoup/soup-value-utils.c @@ -15,7 +15,7 @@ /** * SECTION:soup-value-utils - * @short_description: #GValue utilities + * @short_description: GValue utilities * * These methods are useful for manipulating #GValues, and in * particular, arrays and hash tables of #GValues, in a -- 2.7.4