From 91b1fb36ed8a35c8f42d09e776866d442be13f05 Mon Sep 17 00:00:00 2001 From: Dan Winship Date: Wed, 11 Mar 2009 17:51:43 +0000 Subject: [PATCH] add more detail to the doc comment * libsoup/soup-session.c (soup_session_cancel_message): add more detail to the doc comment * libsoup/soup-message.c (SoupMessage): Note in the doc comment that reason phrases are not very useful, and should not be presented to the user. * libsoup/soup-status.c: add a comment explaining why reason phrases aren't localized. Also some misc doc fixes. (soup_status_get_phrase): Note in the doc comment that you shouldn't present reason phrases to the user. svn path=/trunk/; revision=1248 --- ChangeLog | 14 ++++++++++++++ libsoup/soup-message.c | 11 +++++++++++ libsoup/soup-session.c | 21 ++++++++++++++++++--- libsoup/soup-status.c | 42 +++++++++++++++++++++++++++++++----------- 4 files changed, 74 insertions(+), 14 deletions(-) diff --git a/ChangeLog b/ChangeLog index 4c021e0..8c393ed 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2009-03-11 Dan Winship + + * libsoup/soup-session.c (soup_session_cancel_message): add more + detail to the doc comment + + * libsoup/soup-message.c (SoupMessage): Note in the doc comment + that reason phrases are not very useful, and should not be + presented to the user. + + * libsoup/soup-status.c: add a comment explaining why reason + phrases aren't localized. Also some misc doc fixes. + (soup_status_get_phrase): Note in the doc comment that you + shouldn't present reason phrases to the user. + 2009-03-09 Dan Winship Bug 571527 – gvfsd-http crashed with SIGSEGV in diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c index c7df0d3..a600f0f 100644 --- a/libsoup/soup-message.c +++ b/libsoup/soup-message.c @@ -52,6 +52,17 @@ * * Represents an HTTP message being sent or received. * + * @status_code will normally be a #SoupKnownStatusCode, eg, + * %SOUP_STATUS_OK, though of course it might actually be an unknown + * status code. @reason_phrase is the actual text returned from the + * server, which may or may not correspond to the "standard" + * description of @status_code. At any rate, it is almost certainly + * not localized, and not very descriptive even if it is in the user's + * language; you should not use @reason_phrase in user-visible + * messages. Rather, you should look at @status_code, and determine an + * end-user-appropriate message based on that and on what you were + * trying to do. + * * As described in the #SoupMessageBody documentation, the * @request_body and @response_body %data fields will not necessarily * be filled in at all times. When they are filled in, they will be diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c index c5e0006..fa66fd7 100644 --- a/libsoup/soup-session.c +++ b/libsoup/soup-session.c @@ -1390,9 +1390,24 @@ cancel_message (SoupSession *session, SoupMessage *msg, guint status_code) * @status_code: status code to set on @msg (generally * %SOUP_STATUS_CANCELLED) * - * Causes @session to immediately finish processing @msg, with a final - * status_code of @status_code. Depending on when you cancel it, the - * response state may be incomplete or inconsistent. + * Causes @session to immediately finish processing @msg (regardless + * of its current state) with a final status_code of @status_code. You + * may call this at any time after handing @msg off to @session; if + * @session has started sending the request but has not yet received + * the complete response, then it will close the request's connection. + * Note that with non-idempotent requests (eg, %POST, %PUT, %DELETE) + * it is possible that you might cancel the request after the server + * acts on it, but before it returns a response, leaving the remote + * resource in an unknown state. + * + * If the message is cancelled while its response body is being read, + * then the response body in @msg will be left partially-filled-in. + * The response headers, on the other hand, will always be either + * empty or complete. + * + * For messages queued with soup_session_queue_message() (and + * cancelled from the same thread), the callback will be invoked + * before soup_session_cancel_message() returns. **/ void soup_session_cancel_message (SoupSession *session, SoupMessage *msg, diff --git a/libsoup/soup-status.c b/libsoup/soup-status.c index 668bd7b..9138260 100644 --- a/libsoup/soup-status.c +++ b/libsoup/soup-status.c @@ -77,8 +77,7 @@ * @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_TRY_AGAIN: Formerly used internally. Now unused. * @SOUP_STATUS_CONTINUE: 100 Continue (HTTP) * @SOUP_STATUS_SWITCHING_PROTOCOLS: 101 Switching Protocols (HTTP) * @SOUP_STATUS_PROCESSING: 102 Processing (WebDAV) @@ -156,6 +155,19 @@ * value. **/ + +/* The reason_phrases are not localized because: + * + * 1. Only ASCII can be used portably in the HTTP Status-Line, so we + * would not be able to return localized reason phrases from + * SoupServer anyway. + * + * 2. Having a way for clients to get a localized version of a status + * code would just encourage them to present those strings to the + * user, which is bad because many of them are fairly + * incomprehensible anyway. + */ + static const struct { guint code; const char *phrase; @@ -169,7 +181,6 @@ static const struct { { SOUP_STATUS_SSL_FAILED, "SSL handshake failed" }, { SOUP_STATUS_IO_ERROR, "Connection terminated unexpectedly" }, { SOUP_STATUS_MALFORMED, "Message Corrupt" }, - /* SOUP_STATUS_TRY_AGAIN should never be returned to the caller */ /* Informational */ { SOUP_STATUS_CONTINUE, "Continue" }, @@ -235,13 +246,21 @@ static const struct { * soup_status_get_phrase: * @status_code: an HTTP status code * - * Looks up the stock HTTP description of @status_code. + * Looks up the stock HTTP description of @status_code. This is used + * by soup_message_set_status() to get the correct text to go with a + * given status code. * - * You should not need to use this; if you are interested in the - * textual description for the %status_code of a given #SoupMessage, - * just look at the message's %reason_phrase. + * There is no reason for you to ever use this + * function. If you wanted the textual description for the + * %status_code of a given #SoupMessage, you should just look at the + * message's %reason_phrase. However, you should only do that for use + * in debugging messages; HTTP reason phrases are not localized, and + * are not generally very descriptive anyway, and so they should never + * be presented to the user directly. Instead, you should create you + * own error messages based on the status code, and on what you were + * trying to do. * - * Return value: the (English) description of @status_code + * Return value: the (terse, English) description of @status_code **/ const char * soup_status_get_phrase (guint status_code) @@ -260,9 +279,10 @@ soup_status_get_phrase (guint status_code) * soup_status_proxify: * @status_code: a status code * - * Turns SOUP_STATUS_CANT_RESOLVE into SOUP_STATUS_CANT_RESOLVE_PROXY - * and SOUP_STATUS_CANT_CONNECT into SOUP_STATUS_CANT_CONNECT_PROXY. - * Other status codes are passed through unchanged. + * Turns %SOUP_STATUS_CANT_RESOLVE into + * %SOUP_STATUS_CANT_RESOLVE_PROXY and %SOUP_STATUS_CANT_CONNECT into + * %SOUP_STATUS_CANT_CONNECT_PROXY. Other status codes are passed + * through unchanged. * * Return value: the "proxified" equivalent of @status_code. * -- 2.7.4