[libsoup] soup-server: clarify soup_server_[un]pause_message() documentation

[Dan Winship <danw src gnome org>]

commit a241493298bc87748a79fdfaa7e7f1d657906065
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Wed Oct 23 08:57:45 2013 +0100

    soup-server: clarify soup_server_[un]pause_message() documentation
    
    If a SoupMessage which hasn’t yet started to be received is passed
    into soup_server_[un]pause_message(), an assertion will fail in
    soup-message-io.c because the message doesn’t yet have any I/O data.
    
    Document that passing such SoupMessages into those methods is naughty
    and shouldn’t be done.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=710602

 libsoup/soup-server.c |    8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)
---
diff --git a/libsoup/soup-server.c b/libsoup/soup-server.c
index 3d3070a..07d801d 100644
--- a/libsoup/soup-server.c
+++ b/libsoup/soup-server.c
@@ -1551,6 +1551,10 @@ soup_server_remove_auth_domain (SoupServer *server, SoupAuthDomain *auth_domain)
  * Pauses I/O on @msg. This can be used when you need to return from
  * the server handler without having the full response ready yet. Use
  * soup_server_unpause_message() to resume I/O.
+ *
+ * This must only be called on #SoupMessages which were created by the
+ * #SoupServer and are currently doing I/O, such as those passed into a
+ * #SoupServerCallback or emitted in a #SoupServer::request-read signal.
  **/
 void
 soup_server_pause_message (SoupServer *server,
@@ -1572,6 +1576,10 @@ soup_server_pause_message (SoupServer *server,
  * chunked response.
  *
  * I/O won't actually resume until you return to the main loop.
+ *
+ * This must only be called on #SoupMessages which were created by the
+ * #SoupServer and are currently doing I/O, such as those passed into a
+ * #SoupServerCallback or emitted in a #SoupServer::request-read signal.
  **/
 void
 soup_server_unpause_message (SoupServer *server,