21 files changed, 69 insertions, 62 deletions
diff --git a/libsoup/soup-address.c b/libsoup/soup-address.c
index ecbd9a7f..59598b26 100644
--- a/libsoup/soup-address.c
+++ b/libsoup/soup-address.c
@@ -370,7 +370,7 @@ soup_address_new (const char *name, guint port)
  * Returns a #SoupAddress equivalent to @sa (or %NULL if @sa's
  * address family isn't supported)
  *
- * Return value: (allow-none): the new #SoupAddress
+ * Return value: (nullable): the new #SoupAddress
  **/
 SoupAddress *
 soup_address_new_from_sockaddr (struct sockaddr *sa, int len)
@@ -420,7 +420,7 @@ soup_address_new_from_gsockaddr (GSocketAddress *addr)
  * for @family (or %NULL if @family isn't supported), suitable for
  * using as a listening #SoupSocket.
  *
- * Return value: (allow-none): the new #SoupAddress
+ * Return value: (nullable): the new #SoupAddress
  **/
 SoupAddress *
 soup_address_new_any (SoupAddressFamily family, guint port)
@@ -445,7 +445,7 @@ soup_address_new_any (SoupAddressFamily family, guint port)
  * soup_address_is_resolved() to safely test whether or not an address
  * is resolved before fetching its name or address.
  *
- * Return value: (allow-none): the hostname, or %NULL if it is not known.
+ * Return value: (nullable): the hostname, or %NULL if it is not known.
  **/
 const char *
 soup_address_get_name (SoupAddress *addr)
@@ -468,7 +468,7 @@ soup_address_get_name (SoupAddress *addr)
  * soup_address_is_resolved() to safely test whether or not an address
  * is resolved before fetching its name or address.
  *
- * Return value: (allow-none) (transfer none): the sockaddr, or %NULL
+ * Return value: (nullable) (transfer none): the sockaddr, or %NULL
  **/
 struct sockaddr *
 soup_address_get_sockaddr (SoupAddress *addr, int *len)
@@ -530,7 +530,7 @@ soup_address_make_inet_address (SoupAddress *addr)
  * soup_address_is_resolved() to safely test whether or not an address
  * is resolved before fetching its name or address.
  *
- * Return value: (allow-none): the physical address, or %NULL
+ * Return value: (nullable): the physical address, or %NULL
  **/
 const char *
 soup_address_get_physical (SoupAddress *addr)
diff --git a/libsoup/soup-auth-domain-digest.c b/libsoup/soup-auth-domain-digest.c
index ebf3ddb6..bd7b9513 100644
--- a/libsoup/soup-auth-domain-digest.c
+++ b/libsoup/soup-auth-domain-digest.c
@@ -145,8 +145,9 @@ soup_auth_domain_digest_new (const char *optname1, ...)
  * and return the corresponding encoded password (see
  * soup_auth_domain_digest_encode_password()).
  *
- * Return value: the encoded password, or %NULL if @username is not a
- * valid user. @domain will free the password when it is done with it.
+ * Return value: (nullable): the encoded password, or %NULL if
+ * @username is not a valid user. @domain will free the password when
+ * it is done with it.
  **/
 
 /**
diff --git a/libsoup/soup-auth-domain.c b/libsoup/soup-auth-domain.c
index 2ac37e3a..3b2c0355 100644
--- a/libsoup/soup-auth-domain.c
+++ b/libsoup/soup-auth-domain.c
@@ -572,8 +572,8 @@ soup_auth_domain_covers (SoupAuthDomain *domain, SoupMessage *msg)
  * This is used by #SoupServer internally and is probably of no use to
  * anyone else.
  *
- * Return value: the username that @msg has authenticated as, if in
- * fact it has authenticated. %NULL otherwise.
+ * Return value: (nullable): the username that @msg has authenticated
+ * as, if in fact it has authenticated. %NULL otherwise.
  **/
 char *
 soup_auth_domain_accepts (SoupAuthDomain *domain, SoupMessage *msg)
diff --git a/libsoup/soup-auth.c b/libsoup/soup-auth.c
index 7c34dcfa..3c645225 100644
--- a/libsoup/soup-auth.c
+++ b/libsoup/soup-auth.c
@@ -219,8 +219,8 @@ soup_auth_class_init (SoupAuthClass *auth_class)
  * This is called by #SoupSession; you will normally not create auths
  * yourself.
  *
- * Return value: the new #SoupAuth, or %NULL if it could not be
- * created
+ * Return value: (nullable): the new #SoupAuth, or %NULL if it could
+ * not be created
  **/
 SoupAuth *
 soup_auth_new (GType type, SoupMessage *msg, const char *auth_header)
diff --git a/libsoup/soup-cookie-jar.c b/libsoup/soup-cookie-jar.c
index 48b5c6cb..cd5f30e0 100644
--- a/libsoup/soup-cookie-jar.c
+++ b/libsoup/soup-cookie-jar.c
@@ -371,8 +371,8 @@ get_cookies (SoupCookieJar *jar, SoupURI *uri, gboolean for_http, gboolean copy_
  * almost certainly be setting @for_http to %FALSE if you are calling
  * this.
  *
- * Return value: the cookies, in string form, or %NULL if there are no
- * cookies for @uri.
+ * Return value: (nullable): the cookies, in string form, or %NULL if
+ * there are no cookies for @uri.
  *
  * Since: 2.24
  **/
diff --git a/libsoup/soup-cookie.c b/libsoup/soup-cookie.c
index de5efa13..5af36e91 100755
--- a/libsoup/soup-cookie.c
+++ b/libsoup/soup-cookie.c
@@ -403,9 +403,9 @@ soup_cookie_new (const char *name, const char *value,
  * appropriate string for the domain if you want to actually make use
  * of the cookie.
  *
- * Return value: a new #SoupCookie, or %NULL if it could not be
- * parsed, or contained an illegal "domain" attribute for a cookie
- * originating from @origin.
+ * Return value: (nullable): a new #SoupCookie, or %NULL if it could
+ * not be parsed, or contained an illegal "domain" attribute for a
+ * cookie originating from @origin.
  *
  * Since: 2.24
  **/
diff --git a/libsoup/soup-date.c b/libsoup/soup-date.c
index d3dcf6f4..dabae9d4 100644
--- a/libsoup/soup-date.c
+++ b/libsoup/soup-date.c
@@ -466,8 +466,8 @@ parse_textual_date (SoupDate *date, const char *date_string)
  * and reasonable approximations thereof. (Eg, it is lenient about
  * whitespace, leading "0"s, etc.)
  *
- * Return value: a new #SoupDate, or %NULL if @date_string could not
- * be parsed.
+ * Return value: (nullable): a new #SoupDate, or %NULL if @date_string
+ * could not be parsed.
  **/
 SoupDate *
 soup_date_new_from_string (const char *date_string)
diff --git a/libsoup/soup-form.c b/libsoup/soup-form.c
index 4dee5647..448c3c46 100644
--- a/libsoup/soup-form.c
+++ b/libsoup/soup-form.c
@@ -139,8 +139,8 @@ soup_form_decode (const char *encoded_form)
  * need to decode it manually, using soup_multipart_new_from_message()
  * and soup_multipart_get_part().
  *
- * Return value: (element-type utf8 utf8) (transfer full): a hash
- * table containing the name/value pairs (other than
+ * Return value: (nullable) (element-type utf8 utf8) (transfer full):
+ * a hash table containing the name/value pairs (other than
  * @file_control_name) from @msg, which you can free with
  * g_hash_table_destroy(). On error, it will return %NULL.
  *
diff --git a/libsoup/soup-message-body.c b/libsoup/soup-message-body.c
index dfc29fae..bed90689 100644
--- a/libsoup/soup-message-body.c
+++ b/libsoup/soup-message-body.c
@@ -625,7 +625,7 @@ soup_message_body_flatten (SoupMessageBody *body)
  * @body may still potentially have more data, but that data is not
  * currently available).
  *
- * Return value: a #SoupBuffer, or %NULL.
+ * Return value: (nullable): a #SoupBuffer, or %NULL.
  **/
 SoupBuffer *
 soup_message_body_get_chunk (SoupMessageBody *body, goffset offset)
diff --git a/libsoup/soup-message-headers.c b/libsoup/soup-message-headers.c
index 9c704b49..dcbecaac 100644
--- a/libsoup/soup-message-headers.c
+++ b/libsoup/soup-message-headers.c
@@ -299,7 +299,7 @@ soup_message_headers_remove (SoupMessageHeaders *hdrs, const char *name)
  * whichever one makes libsoup most compatible with other HTTP
  * implementations.)
  *
- * Return value: the header's value or %NULL if not found.
+ * Return value: (nullable): the header's value or %NULL if not found.
  *
  * Since: 2.28
  **/
@@ -337,7 +337,7 @@ soup_message_headers_get_one (SoupMessageHeaders *hdrs, const char *name)
  * transformation is allowed, and so an upstream proxy could do the
  * same thing.
  * 
- * Return value: the header's value or %NULL if not found.
+ * Return value: (nullable): the header's value or %NULL if not found.
  *
  * Since: 2.28
  **/
@@ -393,7 +393,7 @@ soup_message_headers_get_list (SoupMessageHeaders *hdrs, const char *name)
  * soup_message_headers_get_list() were introduced, so callers can
  * explicitly state which behavior they are expecting.
  *
- * Return value: as with soup_message_headers_get_list().
+ * Return value: (nullable): as with soup_message_headers_get_list().
  * 
  * Deprecated: Use soup_message_headers_get_one() or
  * soup_message_headers_get_list() instead.
@@ -1273,9 +1273,10 @@ content_type_setter (SoupMessageHeaders *hdrs, const char *value)
  * its value in *@content_type and *@params. @params can be %NULL if you
  * are only interested in the content type itself.
  *
- * Return value: a string with the value of the "Content-Type" header
- * or NULL if @hdrs does not contain that header or it cannot be
- * parsed (in which case *@params will be unchanged).
+ * Return value: (nullable): a string with the value of the
+ * "Content-Type" header or %NULL if @hdrs does not contain that
+ * header or it cannot be parsed (in which case *@params will be
+ * unchanged).
  *
  * Since: 2.26
  **/
diff --git a/libsoup/soup-message-queue.c b/libsoup/soup-message-queue.c
index 575f51f5..436f3eb5 100644
--- a/libsoup/soup-message-queue.c
+++ b/libsoup/soup-message-queue.c
@@ -204,7 +204,7 @@ soup_message_queue_item_unref (SoupMessageQueueItem *item)
  * the item with soup_message_queue_unref_item() when you are done
  * with it.
  *
- * Return value: the queue item for @msg, or %NULL
+ * Return value: (nullable): the queue item for @msg, or %NULL
  **/ 
 SoupMessageQueueItem *
 soup_message_queue_lookup (SoupMessageQueue *queue, SoupMessage *msg)
diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c
index dd1917c2..45f56a4d 100644
--- a/libsoup/soup-message.c
+++ b/libsoup/soup-message.c
@@ -949,8 +949,8 @@ soup_message_class_init (SoupMessageClass *message_class)
  * 
  * Creates a new empty #SoupMessage, which will connect to @uri
  *
- * Return value: the new #SoupMessage (or %NULL if @uri could not
- * be parsed).
+ * Return value: (nullable): the new #SoupMessage (or %NULL if @uri
+ * could not be parsed).
  */
 SoupMessage *
 soup_message_new (const char *method, const char *uri_string)
@@ -1705,7 +1705,7 @@ soup_message_set_status_full (SoupMessage *msg,
  * up to the application to make sure that it gets unpaused when it
  * becomes possible to allocate a new buffer.
  *
- * Return value: the new buffer (or %NULL)
+ * Return value: (nullable): the new buffer (or %NULL)
  *
  * Deprecated: Use #SoupRequest if you want to read into your
  * own buffers.
diff --git a/libsoup/soup-multipart-input-stream.c b/libsoup/soup-multipart-input-stream.c
index dee4e59f..a1a66838 100644
--- a/libsoup/soup-multipart-input-stream.c
+++ b/libsoup/soup-multipart-input-stream.c
@@ -457,8 +457,8 @@ soup_multipart_input_stream_new (SoupMessage  *msg,
  * the part; a new call to this function should be done at that point,
  * to obtain the next part.
  *
- * Return value: (transfer full): a new #GInputStream, or %NULL if
- * there are no more parts
+ * Return value: (nullable) (transfer full): a new #GInputStream, or
+ * %NULL if there are no more parts
  *
  * Since: 2.40
  */
@@ -546,12 +546,13 @@ soup_multipart_input_stream_next_part_async (SoupMultipartInputStream *multipart
  * soup_multipart_input_stream_next_part_finish:
  * @multipart: a #SoupMultipartInputStream.
  * @result: a #GAsyncResult.
- * @error: a #GError location to store any error, or NULL to ignore.
+ * @error: a #GError location to store any error, or %NULL to ignore.
  *
  * Finishes an asynchronous request for the next part.
  *
- * Return value: (transfer full): a newly created #GInputStream for
- * reading the next part or %NULL if there are no more parts.
+ * Return value: (nullable) (transfer full): a newly created
+ * #GInputStream for reading the next part or %NULL if there are no
+ * more parts.
  *
  * Since: 2.40
  */
@@ -579,9 +580,9 @@ soup_multipart_input_stream_next_part_finish (SoupMultipartInputStream	*multipar
  * Note that if a part had no headers at all an empty #SoupMessageHeaders
  * will be returned.
  *
- * Return value: (transfer none): a #SoupMessageHeaders containing the headers
- * for the part currently being processed or %NULL if the headers failed to
- * parse.
+ * Return value: (nullable) (transfer none): a #SoupMessageHeaders
+ * containing the headers for the part currently being processed or
+ * %NULL if the headers failed to parse.
  *
  * Since: 2.40
  */
diff --git a/libsoup/soup-multipart.c b/libsoup/soup-multipart.c
index aa0b04bf..d6e08e65 100644
--- a/libsoup/soup-multipart.c
+++ b/libsoup/soup-multipart.c
@@ -130,8 +130,8 @@ find_boundary (const char *start, const char *end,
  *
  * Parses @headers and @body to form a new #SoupMultipart
  *
- * Return value: a new #SoupMultipart (or %NULL if the message couldn't
- * be parsed or wasn't multipart).
+ * Return value: (nullable): a new #SoupMultipart (or %NULL if the
+ * message couldn't be parsed or wasn't multipart).
  *
  * Since: 2.26
  **/
diff --git a/libsoup/soup-path-map.c b/libsoup/soup-path-map.c
index ca280df3..a157a600 100644
--- a/libsoup/soup-path-map.c
+++ b/libsoup/soup-path-map.c
@@ -170,8 +170,8 @@ soup_path_map_remove (SoupPathMap *map, const char *path)
  * specifically associated with @path, it will return the data for the
  * closest parent directory of @path that has data associated with it.
  *
- * Return value: the data set with soup_path_map_add(), or %NULL if no
- * data could be found for @path or any of its ancestors.
+ * Return value: (nullable): the data set with soup_path_map_add(), or
+ * %NULL if no data could be found for @path or any of its ancestors.
  **/
 gpointer
 soup_path_map_lookup (SoupPathMap *map, const char *path)
diff --git a/libsoup/soup-request.c b/libsoup/soup-request.c
index 0dfe3eff..0144cf62 100644
--- a/libsoup/soup-request.c
+++ b/libsoup/soup-request.c
@@ -393,8 +393,8 @@ soup_request_get_content_length (SoupRequest *request)
  * As in the HTTP Content-Type header, this may include parameters
  * after the MIME type.
  *
- * Return value: the type of the data represented by @request,
- *   or %NULL if not known.
+ * Return value: (nullable): the type of the data represented by
+ *   @request, or %NULL if not known.
  *
  * Since: 2.42
  */
diff --git a/libsoup/soup-server.c b/libsoup/soup-server.c
index 13d6e5e5..30dc4f9b 100644
--- a/libsoup/soup-server.c
+++ b/libsoup/soup-server.c
@@ -903,8 +903,9 @@ soup_server_class_init (SoupServerClass *server_class)
  * Creates a new #SoupServer. This is exactly equivalent to calling
  * g_object_new() and specifying %SOUP_TYPE_SERVER as the type.
  *
- * Return value: a new #SoupServer. If you are using certain legacy
- * properties, this may also return %NULL if an error occurs.
+ * Return value: (nullable): a new #SoupServer. If you are using
+ * certain legacy properties, this may also return %NULL if an error
+ * occurs.
  **/
 SoupServer *
 soup_server_new (const char *optname1, ...)
@@ -1962,8 +1963,8 @@ soup_server_get_uris (SoupServer *server)
  * This does not add a ref to the context, so you will need to ref it
  * yourself if you want it to outlive its server.
  *
- * Return value: (transfer none): @server's #GMainContext, which may
- * be %NULL
+ * Return value: (nullable) (transfer none): @server's #GMainContext,
+ * which may be %NULL
  *
  * Deprecated: If you are using soup_server_listen(), etc, then
  * the server listens on the thread-default #GMainContext, and this
@@ -2145,7 +2146,7 @@ soup_client_context_get_host (SoupClientContext *client)
  * authenticated, and if so returns the #SoupAuthDomain that
  * authenticated it.
  *
- * Return value: (transfer none) (allow-none): a #SoupAuthDomain, or
+ * Return value: (transfer none) (nullable): a #SoupAuthDomain, or
  * %NULL if the request was not authenticated.
  **/
 SoupAuthDomain *
@@ -2164,8 +2165,8 @@ soup_client_context_get_auth_domain (SoupClientContext *client)
  * authenticated, and if so returns the username that the client
  * authenticated as.
  *
- * Return value: the authenticated-as user, or %NULL if the request
- * was not authenticated.
+ * Return value: (nullable): the authenticated-as user, or %NULL if
+ * the request was not authenticated.
  **/
 const char *
 soup_client_context_get_auth_user (SoupClientContext *client)
diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c
index e1b94e59..f2bd34b9 100644
--- a/libsoup/soup-session.c
+++ b/libsoup/soup-session.c
@@ -939,8 +939,8 @@ soup_session_new_with_options (const char *optname1,
  * For a modern #SoupSession, this will always just return the
  * thread-default #GMainContext, and so is not especially useful.
  *
- * Return value: (transfer none): @session's #GMainContext, which may
- * be %NULL
+ * Return value: (nullable) (transfer none): @session's #GMainContext,
+ * which may be %NULL
  **/
 GMainContext *
 soup_session_get_async_context (SoupSession *session)
@@ -2892,8 +2892,8 @@ soup_session_get_features (SoupSession *session, GType feature_type)
  * features where there may be more than one feature of a given type,
  * use soup_session_get_features().
  *
- * Return value: (transfer none): a #SoupSessionFeature, or %NULL. The
- * feature is owned by @session.
+ * Return value: (nullable) (transfer none): a #SoupSessionFeature, or
+ * %NULL. The feature is owned by @session.
  *
  * Since: 2.26
  **/
@@ -2939,7 +2939,7 @@ soup_session_get_feature (SoupSession *session, GType feature_type)
  * disabled on @msg, and the second is not, then this will return
  * %NULL, not the second feature.
  *
- * Return value: (transfer none): a #SoupSessionFeature, or %NULL. The
+ * Return value: (nullable) (transfer none): a #SoupSessionFeature, or %NULL. The
  * feature is owned by @session.
  *
  * Since: 2.28
diff --git a/libsoup/soup-uri.c b/libsoup/soup-uri.c
index 42c2f680..fcd7d53e 100644
--- a/libsoup/soup-uri.c
+++ b/libsoup/soup-uri.c
@@ -478,8 +478,8 @@ soup_uri_new_with_base (SoupURI *base, const char *uri_string)
  * call at least soup_uri_set_scheme() and soup_uri_set_path(), since
  * those fields are required.)
  *
- * Return value: a #SoupURI, or %NULL if the given string was found to be
- *  invalid.
+ * Return value: (nullable): a #SoupURI, or %NULL if the given string
+ *  was found to be invalid.
  **/
 SoupURI *
 soup_uri_new (const char *uri_string)
diff --git a/libsoup/soup-value-utils.c b/libsoup/soup-value-utils.c
index e1f7c92f..5ae0a694 100644
--- a/libsoup/soup-value-utils.c
+++ b/libsoup/soup-value-utils.c
@@ -266,7 +266,8 @@ G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  * by %G_TYPE_INVALID. (The array will contain copies of the provided
  * data rather than pointing to the passed-in data directly.)
  *
- * Return value: a new #GValueArray, or %NULL if an error occurred.
+ * Return value: (nullable): a new #GValueArray, or %NULL if an error
+ * occurred.
  **/
 GValueArray *
 soup_value_array_from_args (va_list args)
diff --git a/libsoup/soup-xmlrpc.c b/libsoup/soup-xmlrpc.c
index e2890100..ee61da10 100644
--- a/libsoup/soup-xmlrpc.c
+++ b/libsoup/soup-xmlrpc.c
@@ -150,7 +150,8 @@ G_GNUC_END_IGNORE_DEPRECATIONS
  * For structs, use a #GHashTable that maps strings to #GValue;
  * soup_value_hash_new() and related methods can help with this.
  *
- * Return value: the text of the methodCall, or %NULL on error
+ * Return value: (nullable): the text of the methodCall, or %NULL on
+ * error
  **/
 char *
 soup_xmlrpc_build_method_call (const char *method_name,
@@ -256,7 +257,8 @@ soup_xmlrpc_request_new (const char *uri, const char *method_name, ...)
  * The glib type to XML-RPC type mapping is as with
  * soup_xmlrpc_build_method_call(), qv.
  *
- * Return value: the text of the methodResponse, or %NULL on error
+ * Return value: (nullable): the text of the methodResponse, or %NULL
+ * on error
  **/
 char *
 soup_xmlrpc_build_method_response (GValue *value)