docs: use Returns instead of Return value in documentation

32 files changed, 156 insertions, 156 deletions

diff --git a/libsoup/auth/soup-auth.c b/libsoup/auth/soup-auth.c
index d48b908e..710b095b 100644
--- a/libsoup/auth/soup-auth.c
+++ b/libsoup/auth/soup-auth.c
@@ -255,7 +255,7 @@ soup_auth_class_init (SoupAuthClass *auth_class)
  * This is called by #SoupSession; you will normally not create auths
  * yourself.
  *
- * Return value: (nullable): the new #SoupAuth, or %NULL if it could
+ * Returns: (nullable): the new #SoupAuth, or %NULL if it could
  * not be created
  **/
 SoupAuth *
@@ -314,7 +314,7 @@ soup_auth_new (GType type, SoupMessage *msg, const char *auth_header)
  * possibly un-authenticating it. As with soup_auth_new(), this is
  * normally only used by #SoupSession.
  *
- * Return value: %TRUE if @auth is still a valid (but potentially
+ * Returns: %TRUE if @auth is still a valid (but potentially
  * unauthenticated) #SoupAuth. %FALSE if something about @auth_params
  * could not be parsed or incorporated into @auth at all.
  **/
@@ -415,7 +415,7 @@ soup_auth_cancel (SoupAuth *auth)
  * Tests whether or not @auth is associated with a proxy server rather
  * than an "origin" server.
  *
- * Return value: %TRUE or %FALSE
+ * Returns: %TRUE or %FALSE
  **/
 gboolean
 soup_auth_is_for_proxy (SoupAuth *auth)
@@ -433,7 +433,7 @@ soup_auth_is_for_proxy (SoupAuth *auth)
  *
  * Returns @auth's scheme name. (Eg, "Basic", "Digest", or "NTLM")
  *
- * Return value: the scheme name
+ * Returns: the scheme name
  **/
 const char *
 soup_auth_get_scheme_name (SoupAuth *auth)
@@ -470,7 +470,7 @@ soup_auth_get_authority (SoupAuth *auth)
  * string that is meaningful to the user. (Although it is probably not
  * localized.)
  *
- * Return value: the realm name
+ * Returns: the realm name
  **/
 const char *
 soup_auth_get_realm (SoupAuth *auth)
@@ -491,7 +491,7 @@ soup_auth_get_realm (SoupAuth *auth)
  * identifier refer to the same authentication domain (eg, the URLs
  * associated with them take the same usernames and passwords).
  *
- * Return value: the identifier
+ * Returns: the identifier
  **/
 char *
 soup_auth_get_info (SoupAuth *auth)
@@ -515,7 +515,7 @@ soup_auth_get_info (SoupAuth *auth)
  *
  * Tests if @auth has been given a username and password
  *
- * Return value: %TRUE if @auth has been given a username and password
+ * Returns: %TRUE if @auth has been given a username and password
  **/
 gboolean
 soup_auth_is_authenticated (SoupAuth *auth)
@@ -559,7 +559,7 @@ soup_auth_is_cancelled (SoupAuth *auth)
  * session will only call this if soup_auth_is_authenticated()
  * returned %TRUE.)
  *
- * Return value: the "Authorization" header, which must be freed.
+ * Returns: the "Authorization" header, which must be freed.
  **/
 char *
 soup_auth_get_authorization (SoupAuth *auth, SoupMessage *msg)
@@ -580,7 +580,7 @@ soup_auth_get_authorization (SoupAuth *auth, SoupMessage *msg)
  * some auth types (eg, NTLM), the auth may be sendable (eg, as an
  * authentication request) even before it is authenticated.
  *
- * Return value: %TRUE if @auth is ready to make a request with.
+ * Returns: %TRUE if @auth is ready to make a request with.
  *
  **/
 gboolean
@@ -609,7 +609,7 @@ soup_auth_is_ready (SoupAuth    *auth,
  * Tests if @auth is able to authenticate by providing credentials to the
  * soup_auth_authenticate().
  *
- * Return value: %TRUE if @auth is able to accept credentials.
+ * Returns: %TRUE if @auth is able to accept credentials.
  *
  **/
 gboolean
@@ -637,7 +637,7 @@ soup_auth_can_authenticate (SoupAuth *auth)
  * of @auth's protection space, unless otherwise discovered not to
  * be.)
  *
- * Return value: (element-type utf8) (transfer full): the list of
+ * Returns: (element-type utf8) (transfer full): the list of
  * paths, which can be freed with soup_auth_free_protection_space().
  **/
 GSList *
diff --git a/libsoup/auth/soup-connection-auth.c b/libsoup/auth/soup-connection-auth.c
index b3082316..d315e2aa 100644
--- a/libsoup/auth/soup-connection-auth.c
+++ b/libsoup/auth/soup-connection-auth.c
@@ -84,7 +84,7 @@ soup_connection_auth_finalize (GObject *object)
  * This function is only useful from within implementations of SoupConnectionAuth
  * subclasses.
  *
- * Return value: (transfer none): the connection state
+ * Returns: (transfer none): the connection state
  *
  **/
 gpointer
diff --git a/libsoup/cache/soup-cache.c b/libsoup/cache/soup-cache.c
index c5600eef..deaf9b7d 100644
--- a/libsoup/cache/soup-cache.c
+++ b/libsoup/cache/soup-cache.c
@@ -1668,7 +1668,7 @@ soup_cache_set_max_size (SoupCache *cache,
  *
  * Gets the maximum size of the cache.
  *
- * Return value: the maximum size of the cache, in bytes.
+ * Returns: the maximum size of the cache, in bytes.
  *
  */
 guint
diff --git a/libsoup/content-sniffer/soup-content-sniffer.c b/libsoup/content-sniffer/soup-content-sniffer.c
index b64d2a07..f5a13d18 100644
--- a/libsoup/content-sniffer/soup-content-sniffer.c
+++ b/libsoup/content-sniffer/soup-content-sniffer.c
@@ -790,7 +790,7 @@ sniff_feed_or_html (SoupContentSniffer *sniffer, GBytes *buffer)
  * be influenced by the Content-Type declared in @msg's response
  * headers.
  *
- * Return value: the sniffed Content-Type of @buffer; this will never be %NULL,
+ * Returns: the sniffed Content-Type of @buffer; this will never be %NULL,
  *   but may be "application/octet-stream".
  *
  */
@@ -874,7 +874,7 @@ soup_content_sniffer_sniff (SoupContentSniffer *sniffer, SoupMessage *msg,
  * Gets the number of bytes @sniffer needs in order to properly sniff
  * a buffer.
  *
- * Return value: the number of bytes to sniff
+ * Returns: the number of bytes to sniff
  *
  */
 gsize
diff --git a/libsoup/cookies/soup-cookie-jar-db.c b/libsoup/cookies/soup-cookie-jar-db.c
index ac7536a2..316fd98f 100644
--- a/libsoup/cookies/soup-cookie-jar-db.c
+++ b/libsoup/cookies/soup-cookie-jar-db.c
@@ -124,7 +124,7 @@ soup_cookie_jar_db_get_property (GObject *object, guint prop_id,
  * used for this session, and changes made to it will be lost when the
  * jar is destroyed.)
  *
- * Return value: the new #SoupCookieJar
+ * Returns: the new #SoupCookieJar
  *
  **/
 SoupCookieJar *
diff --git a/libsoup/cookies/soup-cookie-jar-text.c b/libsoup/cookies/soup-cookie-jar-text.c
index 9e1e899c..5ff215dd 100644
--- a/libsoup/cookies/soup-cookie-jar-text.c
+++ b/libsoup/cookies/soup-cookie-jar-text.c
@@ -118,7 +118,7 @@ soup_cookie_jar_text_get_property (GObject *object, guint prop_id,
  * used for this session, and changes made to it will be lost when the
  * jar is destroyed.)
  *
- * Return value: the new #SoupCookieJar
+ * Returns: the new #SoupCookieJar
  *
  **/
 SoupCookieJar *
diff --git a/libsoup/cookies/soup-cookie-jar.c b/libsoup/cookies/soup-cookie-jar.c
index 50339376..949e384d 100644
--- a/libsoup/cookies/soup-cookie-jar.c
+++ b/libsoup/cookies/soup-cookie-jar.c
@@ -389,7 +389,7 @@ get_cookies (SoupCookieJar *jar,
  * almost certainly be setting @for_http to %FALSE if you are calling
  * this.
  *
- * Return value: (nullable): the cookies, in string form, or %NULL if
+ * Returns: (nullable): the cookies, in string form, or %NULL if
  * there are no cookies for @uri.
  *
  **/
@@ -435,7 +435,7 @@ soup_cookie_jar_get_cookies (SoupCookieJar *jar, GUri *uri,
  * almost certainly be setting @for_http to %FALSE if you are calling
  * this.
  *
- * Return value: (transfer full) (element-type Soup.Cookie): a #GSList
+ * Returns: (transfer full) (element-type Soup.Cookie): a #GSList
  * with the cookies in the @jar that would be sent with a request to @uri.
  *
  **/
@@ -465,7 +465,7 @@ soup_cookie_jar_get_cookie_list (SoupCookieJar *jar, GUri *uri, gboolean for_htt
  * [SameSite cookies spec](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00)
  * for more detailed information.
  *
- * Return value: (transfer full) (element-type Soup.Cookie): a #GSList
+ * Returns: (transfer full) (element-type Soup.Cookie): a #GSList
  * with the cookies in the @jar that would be sent with a request to @uri.
  *
  */
@@ -855,7 +855,7 @@ soup_cookie_jar_session_feature_init (SoupSessionFeatureInterface *feature_inter
  * The cookies in the list are a copy of the original, so
  * you have to free them when you are done with them.
  *
- * Return value: (transfer full) (element-type Soup.Cookie): a #GSList
+ * Returns: (transfer full) (element-type Soup.Cookie): a #GSList
  * with all the cookies in the @jar.
  *
  **/
diff --git a/libsoup/cookies/soup-cookie.c b/libsoup/cookies/soup-cookie.c
index a300738b..a1c27a68 100644
--- a/libsoup/cookies/soup-cookie.c
+++ b/libsoup/cookies/soup-cookie.c
@@ -74,7 +74,7 @@ G_DEFINE_BOXED_TYPE (SoupCookie, soup_cookie, soup_cookie_copy, soup_cookie_free
  *
  * Copies @cookie.
  *
- * Return value: a copy of @cookie
+ * Returns: a copy of @cookie
  *
  **/
 SoupCookie *
@@ -104,7 +104,7 @@ soup_cookie_copy (SoupCookie *cookie)
  * @cookie should be sent when making a request to @host, or that
  * @cookie should be accepted when receiving a response from @host.
  * 
- * Return value: %TRUE if the domains match, %FALSE otherwise
+ * Returns: %TRUE if the domains match, %FALSE otherwise
  *
  **/
 gboolean
@@ -368,7 +368,7 @@ cookie_new_internal (const char *name, const char *value,
  * about setting the exact time that the cookie will expire, use
  * soup_cookie_set_expires().)
  *
- * Return value: a new #SoupCookie.
+ * Returns: a new #SoupCookie.
  *
  **/
 SoupCookie *
@@ -406,7 +406,7 @@ 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: (nullable): a new #SoupCookie, or %NULL if it could
+ * Returns: (nullable): a new #SoupCookie, or %NULL if it could
  * not be parsed, or contained an illegal "domain" attribute for a
  * cookie originating from @origin.
  *
@@ -423,7 +423,7 @@ soup_cookie_parse (const char *cookie, GUri *origin)
  *
  * Gets @cookie's name
  *
- * Return value: @cookie's name
+ * Returns: @cookie's name
  *
  **/
 const char *
@@ -453,7 +453,7 @@ soup_cookie_set_name (SoupCookie *cookie, const char *name)
  *
  * Gets @cookie's value
  *
- * Return value: @cookie's value
+ * Returns: @cookie's value
  *
  **/
 const char *
@@ -483,7 +483,7 @@ soup_cookie_set_value (SoupCookie *cookie, const char *value)
  *
  * Gets @cookie's domain
  *
- * Return value: @cookie's domain
+ * Returns: @cookie's domain
  *
  **/
 const char *
@@ -513,7 +513,7 @@ soup_cookie_set_domain (SoupCookie *cookie, const char *domain)
  *
  * Gets @cookie's path
  *
- * Return value: @cookie's path
+ * Returns: @cookie's path
  *
  **/
 const char *
@@ -609,7 +609,7 @@ soup_cookie_set_max_age (SoupCookie *cookie, int max_age)
  *
  * Gets @cookie's expiration time.
  *
- * Return value: (nullable) (transfer none): @cookie's expiration
+ * Returns: (nullable) (transfer none): @cookie's expiration
  * time, which is owned by @cookie and should not be modified or
  * freed.
  *
@@ -650,7 +650,7 @@ soup_cookie_set_expires (SoupCookie *cookie, GDateTime *expires)
  *
  * Gets @cookie's secure attribute
  *
- * Return value: @cookie's secure attribute
+ * Returns: @cookie's secure attribute
  *
  **/
 gboolean
@@ -681,7 +681,7 @@ soup_cookie_set_secure (SoupCookie *cookie, gboolean secure)
  *
  * Gets @cookie's HttpOnly attribute
  *
- * Return value: @cookie's HttpOnly attribute
+ * Returns: @cookie's HttpOnly attribute
  *
  **/
 gboolean
@@ -811,7 +811,7 @@ soup_cookie_get_same_site_policy (SoupCookie *cookie)
  * Serializes @cookie in the format used by the Set-Cookie header
  * (ie, for sending a cookie from a #SoupServer to a client).
  *
- * Return value: the header
+ * Returns: the header
  *
  **/
 char *
@@ -830,7 +830,7 @@ soup_cookie_to_set_cookie_header (SoupCookie *cookie)
  * Serializes @cookie in the format used by the Cookie header (ie, for
  * returning a cookie from a #SoupSession to a server).
  *
- * Return value: the header
+ * Returns: the header
  *
  **/
 char *
@@ -872,7 +872,7 @@ soup_cookie_free (SoupCookie *cookie)
  * #SoupCookie<!-- -->s. Cookies that do not specify "path" or
  * "domain" attributes will have their values defaulted from @msg.
  *
- * Return value: (element-type SoupCookie) (transfer full): a #GSList
+ * Returns: (element-type SoupCookie) (transfer full): a #GSList
  * of #SoupCookie<!-- -->s, which can be freed with
  * soup_cookies_free().
  *
@@ -915,7 +915,7 @@ soup_cookies_from_response (SoupMessage *msg)
  * pass a cookie returned from this method directly to
  * soup_cookies_to_response().)
  *
- * Return value: (element-type SoupCookie) (transfer full): a #GSList
+ * Returns: (element-type SoupCookie) (transfer full): a #GSList
  * of #SoupCookie<!-- -->s, which can be freed with
  * soup_cookies_free().
  *
@@ -1022,7 +1022,7 @@ soup_cookies_free (GSList *cookies)
  * Serializes a #GSList of #SoupCookie into a string suitable for
  * setting as the value of the "Cookie" header.
  *
- * Return value: the serialization of @cookies
+ * Returns: the serialization of @cookies
  *
  **/
 char *
@@ -1052,7 +1052,7 @@ soup_cookies_to_cookie_header (GSList *cookies)
  * @uri, because it assumes that the caller has already done that.
  * But don't rely on that; it may change in the future.)
  *
- * Return value: %TRUE if @cookie should be sent to @uri, %FALSE if
+ * Returns: %TRUE if @cookie should be sent to @uri, %FALSE if
  * not
  *
  **/
@@ -1096,7 +1096,7 @@ soup_cookie_applies_to_uri (SoupCookie *cookie, GUri *uri)
  * Note that currently, this does not check that the cookie domains
  * match. This may change in the future.
  *
- * Return value: whether the cookies are equal.
+ * Returns: whether the cookies are equal.
  *
  */
 gboolean
diff --git a/libsoup/hsts/soup-hsts-enforcer-db.c b/libsoup/hsts/soup-hsts-enforcer-db.c
index 572a8862..55f13ea9 100644
--- a/libsoup/hsts/soup-hsts-enforcer-db.c
+++ b/libsoup/hsts/soup-hsts-enforcer-db.c
@@ -116,7 +116,7 @@ soup_hsts_enforcer_db_get_property (GObject *object, guint prop_id,
  * #SoupHSTSEnforcerDB will be written to @filename when
  * #SoupHSTSEnforcer::changed is emitted.
  *
- * Return value: the new #SoupHSTSEnforcer
+ * Returns: the new #SoupHSTSEnforcer
  *
  **/
 SoupHSTSEnforcer *
diff --git a/libsoup/server/soup-auth-domain-basic.c b/libsoup/server/soup-auth-domain-basic.c
index 1fa37563..1f66b96e 100644
--- a/libsoup/server/soup-auth-domain-basic.c
+++ b/libsoup/server/soup-auth-domain-basic.c
@@ -120,7 +120,7 @@ soup_auth_domain_basic_get_property (GObject *object, guint prop_id,
  * returned with the authentication challenge to the client. Other
  * parameters are optional.
  *
- * Return value: the new #SoupAuthDomain
+ * Returns: the new #SoupAuthDomain
  **/
 SoupAuthDomain *
 soup_auth_domain_basic_new (const char *optname1, ...)
@@ -161,7 +161,7 @@ soup_auth_domain_basic_new (const char *optname1, ...)
  * database may give attackers access to other more-interesting sites
  * as well.
  *
- * Return value: %TRUE if @username and @password are valid
+ * Returns: %TRUE if @username and @password are valid
  **/
 
 /**
diff --git a/libsoup/server/soup-auth-domain-digest.c b/libsoup/server/soup-auth-domain-digest.c
index 5ecf4045..82087d97 100644
--- a/libsoup/server/soup-auth-domain-digest.c
+++ b/libsoup/server/soup-auth-domain-digest.c
@@ -124,7 +124,7 @@ soup_auth_domain_digest_get_property (GObject *object, guint prop_id,
  * returned with the authentication challenge to the client. Other
  * parameters are optional.
  *
- * Return value: the new #SoupAuthDomain
+ * Returns: the new #SoupAuthDomain
  **/
 SoupAuthDomain *
 soup_auth_domain_digest_new (const char *optname1, ...)
@@ -154,7 +154,7 @@ soup_auth_domain_digest_new (const char *optname1, ...)
  * and return the corresponding encoded password (see
  * soup_auth_domain_digest_encode_password()).
  *
- * Return value: (nullable): the encoded password, or %NULL if
+ * Returns: (nullable): the encoded password, or %NULL if
  * @username is not a valid user. @domain will free the password when
  * it is done with it.
  **/
@@ -364,7 +364,7 @@ soup_auth_domain_digest_challenge (SoupAuthDomain    *domain,
  * that the encoded password returned by this method is identical to
  * the encoded password stored in an Apache .htdigest file.)
  *
- * Return value: the encoded password
+ * Returns: the encoded password
  **/
 char *
 soup_auth_domain_digest_encode_password (const char *username,
diff --git a/libsoup/server/soup-auth-domain.c b/libsoup/server/soup-auth-domain.c
index 5606f818..efa01ec4 100644
--- a/libsoup/server/soup-auth-domain.c
+++ b/libsoup/server/soup-auth-domain.c
@@ -314,7 +314,7 @@ soup_auth_domain_remove_path (SoupAuthDomain *domain, const char *path)
  * The prototype for a #SoupAuthDomain filter; see
  * soup_auth_domain_set_filter() for details.
  *
- * Return value: %TRUE if @msg requires authentication, %FALSE if not.
+ * Returns: %TRUE if @msg requires authentication, %FALSE if not.
  **/
 
 /**
@@ -375,7 +375,7 @@ soup_auth_domain_set_filter (SoupAuthDomain *domain,
  *
  * Gets the realm name associated with @domain
  *
- * Return value: @domain's realm
+ * Returns: @domain's realm
  **/
 const char *
 soup_auth_domain_get_realm (SoupAuthDomain *domain)
@@ -410,7 +410,7 @@ soup_auth_domain_get_realm (SoupAuthDomain *domain)
  * #SoupServer is used, this is not really relevant, but it may still
  * be worth considering.
  *
- * Return value: %TRUE if @msg is authenticated, %FALSE if not.
+ * Returns: %TRUE if @msg is authenticated, %FALSE if not.
  **/
 
 /**
@@ -471,7 +471,7 @@ soup_auth_domain_try_generic_auth_callback (SoupAuthDomain    *domain,
  * @password. This would normally be called from a
  * #SoupAuthDomainGenericAuthCallback.
  *
- * Return value: whether or not the message is authenticated
+ * Returns: whether or not the message is authenticated
  **/
 gboolean
 soup_auth_domain_check_password (SoupAuthDomain    *domain,
@@ -497,7 +497,7 @@ soup_auth_domain_check_password (SoupAuthDomain    *domain,
  * This is used by #SoupServer internally and is probably of no use to
  * anyone else.
  *
- * Return value: %TRUE if @domain requires @msg to be authenticated
+ * Returns: %TRUE if @domain requires @msg to be authenticated
  **/
 gboolean
 soup_auth_domain_covers (SoupAuthDomain    *domain,
@@ -531,7 +531,7 @@ soup_auth_domain_covers (SoupAuthDomain    *domain,
  * This is used by #SoupServer internally and is probably of no use to
  * anyone else.
  *
- * Return value: (nullable): the username that @msg has authenticated
+ * Returns: (nullable): the username that @msg has authenticated
  * as, if in fact it has authenticated. %NULL otherwise.
  **/
 char *
diff --git a/libsoup/server/soup-message-body.c b/libsoup/server/soup-message-body.c
index bb7a6d70..2c7775ad 100644
--- a/libsoup/server/soup-message-body.c
+++ b/libsoup/server/soup-message-body.c
@@ -71,7 +71,7 @@ typedef struct {
  * Creates a new #SoupMessageBody. #SoupMessage uses this internally; you
  * will not normally need to call it yourself.
  *
- * Return value: a new #SoupMessageBody.
+ * Returns: a new #SoupMessageBody.
  **/
 SoupMessageBody *
 soup_message_body_new (void)
@@ -120,7 +120,7 @@ soup_message_body_set_accumulate (SoupMessageBody *body,
  * Gets the accumulate flag on @body; see
  * soup_message_body_set_accumulate() for details.
  *
- * Return value: the accumulate flag for @body.
+ * Returns: the accumulate flag for @body.
  *
  **/
 gboolean
@@ -302,7 +302,7 @@ soup_message_body_flatten (SoupMessageBody *body)
  * @body may still potentially have more data, but that data is not
  * currently available).
  *
- * Return value: (nullable): a #GBytes, or %NULL.
+ * Returns: (nullable): a #GBytes, or %NULL.
  **/
 GBytes *
 soup_message_body_get_chunk (SoupMessageBody *body, goffset offset)
diff --git a/libsoup/server/soup-path-map.c b/libsoup/server/soup-path-map.c
index 6be8eb67..a597c109 100644
--- a/libsoup/server/soup-path-map.c
+++ b/libsoup/server/soup-path-map.c
@@ -38,7 +38,7 @@ struct SoupPathMap {
  *
  * Creates a new %SoupPathMap.
  *
- * Return value: the new %SoupPathMap
+ * Returns: the new %SoupPathMap
  **/
 SoupPathMap *
 soup_path_map_new (GDestroyNotify data_free_func)
@@ -175,7 +175,7 @@ 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: (nullable): the data set with soup_path_map_add(), or
+ * Returns: (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
diff --git a/libsoup/server/soup-server-message.c b/libsoup/server/soup-server-message.c
index bb9a6385..40f92c7e 100644
--- a/libsoup/server/soup-server-message.c
+++ b/libsoup/server/soup-server-message.c
@@ -786,7 +786,7 @@ soup_server_message_set_redirect (SoupServerMessage *msg,
  * not get fooled when the allocator reuses the memory address of a
  * previously-destroyed socket to represent a new socket.
  *
- * Return value: (nullable) (transfer none): the #GSocket that @msg is
+ * Returns: (nullable) (transfer none): the #GSocket that @msg is
  * associated with, %NULL if you used soup_server_accept_iostream().
  */
 GSocket *
@@ -804,7 +804,7 @@ soup_server_message_get_socket (SoupServerMessage *msg)
  * Retrieves the #GSocketAddress associated with the remote end
  * of a connection.
  *
- * Return value: (nullable) (transfer none): the #GSocketAddress
+ * Returns: (nullable) (transfer none): the #GSocketAddress
  *     associated with the remote end of a connection, it may be
  *     %NULL if you used soup_server_accept_iostream().
  */
@@ -830,7 +830,7 @@ soup_server_message_get_remote_address (SoupServerMessage *msg)
  * Retrieves the #GSocketAddress associated with the local end
  * of a connection.
  *
- * Return value: (nullable) (transfer none): the #GSocketAddress
+ * Returns: (nullable) (transfer none): the #GSocketAddress
  *     associated with the local end of a connection, it may be
  *     %NULL if you used soup_server_accept_iostream().
  */
@@ -856,7 +856,7 @@ soup_server_message_get_local_address (SoupServerMessage *msg)
  * Retrieves the IP address associated with the remote end of a
  * connection.
  *
- * Return value: (nullable): the IP address associated with the remote
+ * Returns: (nullable): the IP address associated with the remote
  *     end of a connection, it may be %NULL if you used
  *     soup_server_accept_iostream().
  */
@@ -899,7 +899,7 @@ soup_server_message_get_remote_host (SoupServerMessage *msg)
  * Note that when calling this function from C, @msg will most
  * likely be freed as a side effect.
  *
- * Return value: (transfer full): the #GIOStream formerly associated
+ * Returns: (transfer full): the #GIOStream formerly associated
  *   with @msg (or %NULL if @msg was no longer associated with a
  *   connection). No guarantees are made about what kind of #GIOStream
  *   is returned.
diff --git a/libsoup/server/soup-server.c b/libsoup/server/soup-server.c
index 0b76e271..b793e09a 100644
--- a/libsoup/server/soup-server.c
+++ b/libsoup/server/soup-server.c
@@ -500,7 +500,7 @@ 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: (nullable): a new #SoupServer. If you are using
+ * Returns: (nullable): a new #SoupServer. If you are using
  * certain legacy properties, this may also return %NULL if an error
  * occurs.
  **/
@@ -533,7 +533,7 @@ soup_server_new (const char *optname1, ...)
  * Alternatively, you can set the #SoupServer:tls-certificate property
  * at construction time, if you already have a #GTlsCertificate.
  *
- * Return value: success or failure.
+ * Returns: success or failure.
  *
  */
 gboolean
@@ -575,7 +575,7 @@ soup_server_set_ssl_cert_file  (SoupServer  *server,
  * actually currently is or not. Use soup_server_get_uris() to see if
  * it currently has any https listeners.
  *
- * Return value: %TRUE if @server is configured to serve https.
+ * Returns: %TRUE if @server is configured to serve https.
  **/
 gboolean
 soup_server_is_https (SoupServer *server)
@@ -597,7 +597,7 @@ soup_server_is_https (SoupServer *server)
  * You should treat these sockets as read-only; writing to or
  * modifiying any of these sockets may cause @server to malfunction.
  *
- * Return value: (transfer container) (element-type Gio.Socket): a
+ * Returns: (transfer container) (element-type Gio.Socket): a
  * list of listening sockets.
  **/
 GSList *
@@ -955,7 +955,7 @@ start_request (SoupServer        *server,
  *
  * Add a new client stream to the @server.
  *
- * Return value: %TRUE on success, %FALSE if the stream could not be
+ * Returns: %TRUE on success, %FALSE if the stream could not be
  * accepted or any other error occurred (in which case @error will be
  * set).
  *
@@ -1128,7 +1128,7 @@ soup_server_listen_internal (SoupServer *server, SoupSocket *listener,
  * @address is an IPv6 address, it will only accept IPv6 connections.
  * You must configure IPv4 listening separately.
  *
- * Return value: %TRUE on success, %FALSE if @address could not be
+ * Returns: %TRUE on success, %FALSE if @address could not be
  * bound or any other error occurred (in which case @error will be
  * set).
  *
@@ -1252,7 +1252,7 @@ soup_server_listen_ipv4_ipv6 (SoupServer *server,
  *
  * See soup_server_listen() for more details.
  *
- * Return value: %TRUE on success, %FALSE if @port could not be bound
+ * Returns: %TRUE on success, %FALSE if @port could not be bound
  * or any other error occurred (in which case @error will be set).
  *
  **/
@@ -1305,7 +1305,7 @@ soup_server_listen_all (SoupServer *server, guint port,
  *
  * See soup_server_listen() for more details.
  *
- * Return value: %TRUE on success, %FALSE if @port could not be bound
+ * Returns: %TRUE on success, %FALSE if @port could not be bound
  * or any other error occurred (in which case @error will be set).
  *
  **/
@@ -1352,7 +1352,7 @@ soup_server_listen_local (SoupServer *server, guint port,
  *
  * See soup_server_listen() for more details.
  *
- * Return value: %TRUE on success, %FALSE if an error occurred (in
+ * Returns: %TRUE on success, %FALSE if an error occurred (in
  * which case @error will be set).
  *
  **/
@@ -1399,7 +1399,7 @@ soup_server_listen_socket (SoupServer *server, GSocket *socket,
  * <literal>::</literal>, rather than actually returning separate URIs
  * for each interface on the system.
  *
- * Return value: (transfer full) (element-type GUri): a list of
+ * Returns: (transfer full) (element-type GUri): a list of
  * #GUris, which you must free when you are done with it.
  *
  */
diff --git a/libsoup/server/soup-socket.c b/libsoup/server/soup-socket.c
index f79da2bd..cfdf791b 100644
--- a/libsoup/server/soup-socket.c
+++ b/libsoup/server/soup-socket.c
@@ -412,7 +412,7 @@ soup_socket_initable_interface_init (GInitableIface *initable_interface)
  *
  * Creates a new (disconnected) socket
  *
- * Return value: the new socket
+ * Returns: the new socket
  **/
 SoupSocket *
 soup_socket_new (const char *optname1, ...)
@@ -556,7 +556,7 @@ finish_listener_setup (SoupSocket *sock)
  * Makes @sock start listening on its local address. When connections
  * come in, @sock will emit #SoupSocket::new_connection.
  *
- * Return value: whether or not @sock is now listening.
+ * Returns: whether or not @sock is now listening.
  **/
 gboolean
 soup_socket_listen (SoupSocket *sock,
@@ -620,7 +620,7 @@ soup_socket_listen (SoupSocket *sock,
  *
  * Tests if @sock is doing (or has attempted to do) SSL.
  *
- * Return value: %TRUE if @sock has SSL credentials set
+ * Returns: %TRUE if @sock has SSL credentials set
  **/
 gboolean
 soup_socket_is_ssl (SoupSocket *sock)
@@ -669,7 +669,7 @@ soup_socket_disconnect (SoupSocket *sock)
  *
  * Tests if @sock is connected to another host
  *
- * Return value: %TRUE or %FALSE.
+ * Returns: %TRUE or %FALSE.
  **/
 gboolean
 soup_socket_is_connected (SoupSocket *sock)
@@ -691,7 +691,7 @@ soup_socket_is_connected (SoupSocket *sock)
  * Calling this method on an unconnected socket is considered to be
  * an error, and produces undefined results.
  *
- * Return value: (transfer none): the #GInetSocketAddress
+ * Returns: (transfer none): the #GInetSocketAddress
  **/
 GInetSocketAddress *
 soup_socket_get_local_address (SoupSocket *sock)
@@ -729,7 +729,7 @@ soup_socket_get_local_address (SoupSocket *sock)
  * Calling this method on an unconnected socket is considered to be
  * an error, and produces undefined results.
  *
- * Return value: (transfer none): the #GInetSocketAddress
+ * Returns: (transfer none): the #GInetSocketAddress
  **/
 GInetSocketAddress *
 soup_socket_get_remote_address (SoupSocket *sock)
diff --git a/libsoup/soup-date-utils.c b/libsoup/soup-date-utils.c
index 4e395044..6d4620b7 100644
--- a/libsoup/soup-date-utils.c
+++ b/libsoup/soup-date-utils.c
@@ -39,7 +39,7 @@
  *
  * Determines if @date is in the past.
  *
- * Return value: %TRUE if @date is in the past
+ * Returns: %TRUE if @date is in the past
  */
 gboolean
 soup_date_time_is_past (GDateTime *date)
@@ -310,7 +310,7 @@ parse_textual_date (const char *date_string)
  * dates, and reasonable approximations thereof. (Eg, it is lenient about
  * whitespace, leading "0"s, etc.)
  *
- * Return value: (nullable): a new #GDateTime, or %NULL if @date_string
+ * Returns: (nullable): a new #GDateTime, or %NULL if @date_string
  * could not be parsed.
  **/
 GDateTime *
diff --git a/libsoup/soup-form.c b/libsoup/soup-form.c
index 74c35c1d..30d5bf93 100644
--- a/libsoup/soup-form.c
+++ b/libsoup/soup-form.c
@@ -74,7 +74,7 @@ form_decode (char *part)
  * Decodes @form, which is an urlencoded dataset as defined in the
  * HTML 4.01 spec.
  *
- * Return value: (element-type utf8 utf8) (transfer container): a hash
+ * Returns: (element-type utf8 utf8) (transfer container): a hash
  * table containing the name/value pairs from @encoded_form, which you
  * can free with g_hash_table_destroy().
  **/
@@ -136,7 +136,7 @@ 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: (nullable) (element-type utf8 utf8) (transfer container):
+ * Returns: (nullable) (element-type utf8 utf8) (transfer container):
  * 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.
@@ -245,7 +245,7 @@ encode_pair (GString *str, const char *name, const char *value)
  * working with dynamic forms, use soup_form_encode_hash() or
  * soup_form_encode_datalist().
  *
- * Return value: the encoded form
+ * Returns: the encoded form
  *
  * See also: soup_message_new_from_encoded_form()
  **/
@@ -276,7 +276,7 @@ soup_form_encode (const char *first_field, ...)
  * takes a hash table, it cannot enforce that; if you care about the
  * ordering of the form fields, use soup_form_encode_datalist().
  *
- * Return value: the encoded form
+ * Returns: the encoded form
  *
  * See also: soup_message_new_from_encoded_form()
  **/
@@ -308,7 +308,7 @@ datalist_encode_foreach (GQuark key_id, gpointer value, gpointer str)
  * spec. Unlike soup_form_encode_hash(), this preserves the ordering
  * of the form elements, which may be required in some situations.
  *
- * Return value: the encoded form
+ * Returns: the encoded form
  *
  * See also: soup_message_new_from_encoded_form()
  **/
@@ -329,7 +329,7 @@ soup_form_encode_datalist (GData **form_data_set)
  * See soup_form_encode(). This is mostly an internal method, used by
  * various other methods such as soup_form_encode().
  *
- * Return value: the encoded form
+ * Returns: the encoded form
  *
  * See also: soup_message_new_from_encoded_form()
  **/
diff --git a/libsoup/soup-headers.c b/libsoup/soup-headers.c
index 5daa157d..a14734bc 100644
--- a/libsoup/soup-headers.c
+++ b/libsoup/soup-headers.c
@@ -39,7 +39,7 @@
  * This is a low-level method; normally you would use
  * soup_headers_parse_request() or soup_headers_parse_response().
  *
- * Return value: success or failure
+ * Returns: success or failure
  *
  **/
 gboolean
@@ -180,7 +180,7 @@ done:
  *
  * Beware that @req_headers may be modified even on failure.
  *
- * Return value: %SOUP_STATUS_OK if the headers could be parsed, or an
+ * Returns: %SOUP_STATUS_OK if the headers could be parsed, or an
  * HTTP error to be returned to the client if they could not be.
  **/
 guint
@@ -289,7 +289,7 @@ soup_headers_parse_request (const char          *str,
  * @status_code, and @reason_phrase. @status_line must be terminated by
  * either "\0" or "\r\n".
  *
- * Return value: %TRUE if @status_line was parsed successfully.
+ * Returns: %TRUE if @status_line was parsed successfully.
  **/
 gboolean
 soup_headers_parse_status_line (const char       *status_line,
@@ -367,7 +367,7 @@ soup_headers_parse_status_line (const char       *status_line,
  *
  * Beware that @headers may be modified even on failure.
  *
- * Return value: success or failure.
+ * Returns: success or failure.
  **/
 gboolean
 soup_headers_parse_response (const char          *str, 
@@ -491,7 +491,7 @@ parse_list (const char *header, char delim)
  * "#something", where "something" does not itself contain commas,
  * except as part of quoted-strings.
  *
- * Return value: (transfer full) (element-type utf8): a #GSList of
+ * Returns: (transfer full) (element-type utf8): a #GSList of
  * list elements, as allocated strings
  **/
 GSList *
@@ -535,7 +535,7 @@ sort_by_qval (const void *a, const void *b)
  * items with qvalue 0. Either way, those items will be removed from
  * the main list.
  *
- * Return value: (transfer full) (element-type utf8): a #GSList of
+ * Returns: (transfer full) (element-type utf8): a #GSList of
  * acceptable values (as allocated strings), highest-qvalue first.
  **/
 GSList *
@@ -633,7 +633,7 @@ soup_header_free_list (GSList *list)
  * case-insensitively). Note that this can't be used with lists
  * that have qvalues.
  *
- * Return value: whether or not @header contains @token
+ * Returns: whether or not @header contains @token
  **/
 gboolean
 soup_header_contains (const char *header, const char *token)
@@ -791,7 +791,7 @@ parse_param_list (const char *header, char delim, gboolean strict)
  * for giving UTF8-encoded filenames in the Content-Disposition
  * header).
  *
- * Return value: (element-type utf8 utf8) (transfer full): a
+ * Returns: (element-type utf8 utf8) (transfer full): a
  * #GHashTable of list elements, which can be freed with
  * soup_header_free_param_list().
  **/
@@ -817,7 +817,7 @@ soup_header_parse_param_list (const char *header)
  * for giving UTF8-encoded filenames in the Content-Disposition
  * header).
  *
- * Return value: (element-type utf8 utf8) (transfer full): a
+ * Returns: (element-type utf8 utf8) (transfer full): a
  * #GHashTable of list elements, which can be freed with
  * soup_header_free_param_list().
  *
@@ -842,7 +842,7 @@ soup_header_parse_semi_param_list (const char *header)
  * RFC5987-encoded parameters, use
  * soup_header_parse_param_list() instead.
  *
- * Return value: (element-type utf8 utf8) (transfer full) (nullable):
+ * Returns: (element-type utf8 utf8) (transfer full) (nullable):
  * a #GHashTable of list elements, which can be freed with
  * soup_header_free_param_list() or %NULL if there are duplicate
  * elements.
@@ -868,7 +868,7 @@ soup_header_parse_param_list_strict (const char *header)
  * RFC5987-encoded parameters, use
  * soup_header_parse_semi_param_list() instead.
  *
- * Return value: (element-type utf8 utf8) (transfer full) (nullable):
+ * Returns: (element-type utf8 utf8) (transfer full) (nullable):
  * a #GHashTable of list elements, which can be freed with
  * soup_header_free_param_list() or %NULL if there are duplicate
  * elements.
diff --git a/libsoup/soup-logger.c b/libsoup/soup-logger.c
index 8ac47adf..29a089a1 100644
--- a/libsoup/soup-logger.c
+++ b/libsoup/soup-logger.c
@@ -270,7 +270,7 @@ soup_logger_new (SoupLoggerLogLevel level)
  * return a #SoupLoggerLogLevel value indicating how much of the
  * message to log.
  *
- * Return value: a #SoupLoggerLogLevel value indicating how much of
+ * Returns: a #SoupLoggerLogLevel value indicating how much of
  * the message to log
  **/
 
diff --git a/libsoup/soup-message-headers.c b/libsoup/soup-message-headers.c
index e3dc2cce..723363cc 100644
--- a/libsoup/soup-message-headers.c
+++ b/libsoup/soup-message-headers.c
@@ -70,7 +70,7 @@ struct _SoupMessageHeaders {
  * automatically for its own headers. You would only need to use this
  * method if you are manually parsing or generating message headers.)
  *
- * Return value: a new #SoupMessageHeaders
+ * Returns: a new #SoupMessageHeaders
  **/
 SoupMessageHeaders *
 soup_message_headers_new (SoupMessageHeadersType type)
@@ -121,7 +121,7 @@ G_DEFINE_BOXED_TYPE (SoupMessageHeaders, soup_message_headers, soup_message_head
  *
  * Gets the type of headers.
  *
- * Return value: the header's type.
+ * Returns: the header's type.
  *
  **/
 SoupMessageHeadersType
@@ -321,7 +321,7 @@ soup_message_headers_remove (SoupMessageHeaders *hdrs, const char *name)
  * whichever one makes libsoup most compatible with other HTTP
  * implementations.)
  *
- * Return value: (nullable) (transfer none): the header's value or %NULL if not found.
+ * Returns: (nullable) (transfer none): the header's value or %NULL if not found.
  *
  **/
 const char *
@@ -352,7 +352,7 @@ soup_message_headers_get_one (SoupMessageHeaders *hdrs, const char *name)
  * (If @name is present in @hdrs, then this is equivalent to calling
  * soup_header_contains() on its value.)
  *
- * Return value: %TRUE if the header is present and contains @token,
+ * Returns: %TRUE if the header is present and contains @token,
  *   %FALSE otherwise.
  *
  **/
@@ -376,7 +376,7 @@ soup_message_headers_header_contains (SoupMessageHeaders *hdrs, const char *name
  * Checks whether the header @name is present in @hdrs and is
  * (case-insensitively) equal to @value.
  *
- * Return value: %TRUE if the header is present and its value is
+ * Returns: %TRUE if the header is present and its value is
  *   @value, %FALSE otherwise.
  *
  **/
@@ -409,7 +409,7 @@ soup_message_headers_header_equals (SoupMessageHeaders *hdrs, const char *name,
  * transformation is allowed, and so an upstream proxy could do the
  * same thing.
  * 
- * Return value: (nullable) (transfer none): the header's value or %NULL if not found.
+ * Returns: (nullable) (transfer none): the header's value or %NULL if not found.
  *
  **/
 const char *
@@ -498,7 +498,7 @@ soup_message_headers_iter_init (SoupMessageHeadersIter *iter,
  * then soup_message_headers_iter_next() will return %FALSE and @name
  * and @value will be unchanged.
  *
- * Return value: %TRUE if another name and value were returned, %FALSE
+ * Returns: %TRUE if another name and value were returned, %FALSE
  * if the end of the headers has been reached.
  **/
 gboolean
@@ -692,7 +692,7 @@ content_length_setter (SoupMessageHeaders *hdrs, const char *value)
  * response may declare a Content-Length or Transfer-Encoding, but
  * it will never actually include a body.
  *
- * Return value: the encoding declared by @hdrs.
+ * Returns: the encoding declared by @hdrs.
  **/
 SoupEncoding
 soup_message_headers_get_encoding (SoupMessageHeaders *hdrs)
@@ -771,7 +771,7 @@ soup_message_headers_set_encoding (SoupMessageHeaders *hdrs,
  * be non-0 if soup_message_headers_get_encoding() returns
  * %SOUP_ENCODING_CONTENT_LENGTH.
  *
- * Return value: the message body length declared by @hdrs.
+ * Returns: the message body length declared by @hdrs.
  **/
 goffset
 soup_message_headers_get_content_length (SoupMessageHeaders *hdrs)
@@ -842,7 +842,7 @@ expectation_setter (SoupMessageHeaders *hdrs, const char *value)
  * Currently this will either be %SOUP_EXPECTATION_CONTINUE or
  * %SOUP_EXPECTATION_UNRECOGNIZED.
  *
- * Return value: the contents of @hdrs's "Expect" header
+ * Returns: the contents of @hdrs's "Expect" header
  **/
 SoupExpectation
 soup_message_headers_get_expectations (SoupMessageHeaders *hdrs)
@@ -1043,7 +1043,7 @@ soup_message_headers_get_ranges_internal (SoupMessageHeaders  *hdrs,
  * actually requested by the client.
  * </para></note>
  *
- * Return value: %TRUE if @hdrs contained a syntactically-valid
+ * Returns: %TRUE if @hdrs contained a syntactically-valid
  * "Range" header, %FALSE otherwise (in which case @range and @length
  * will not be set).
  *
@@ -1151,7 +1151,7 @@ soup_message_headers_set_range (SoupMessageHeaders  *hdrs,
  * @end, and @total_length. If the total length field in the header
  * was specified as "*", then @total_length will be set to -1.
  *
- * Return value: %TRUE if @hdrs contained a "Content-Range" header
+ * Returns: %TRUE if @hdrs contained a "Content-Range" header
  * containing a byte range which could be parsed, %FALSE otherwise.
  *
  **/
@@ -1321,7 +1321,7 @@ 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: (nullable): a string with the value of the
+ * Returns: (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).
@@ -1383,7 +1383,7 @@ soup_message_headers_set_content_type (SoupMessageHeaders  *hdrs,
  * this is handled automatically by #SoupMultipart and the associated
  * form methods.
  *
- * Return value: %TRUE if @hdrs contains a "Content-Disposition"
+ * Returns: %TRUE if @hdrs contains a "Content-Disposition"
  * header, %FALSE if not (in which case *@disposition and *@params
  * will be unchanged).
  *
diff --git a/libsoup/soup-message-io.c b/libsoup/soup-message-io.c
index 064f3d35..1957bc9b 100644
--- a/libsoup/soup-message-io.c
+++ b/libsoup/soup-message-io.c
@@ -1022,7 +1022,7 @@ soup_message_io_unpause (SoupMessage *msg)
  *
  * Tests whether or not I/O is currently in progress on @msg.
  *
- * Return value: whether or not I/O is currently in progress.
+ * Returns: whether or not I/O is currently in progress.
  **/
 gboolean
 soup_message_io_in_progress (SoupMessage *msg)
diff --git a/libsoup/soup-message-queue.c b/libsoup/soup-message-queue.c
index 65d2dab3..f1422b19 100644
--- a/libsoup/soup-message-queue.c
+++ b/libsoup/soup-message-queue.c
@@ -70,7 +70,7 @@ queue_message_restarted (SoupMessage *msg, gpointer user_data)
  *
  * Creates a new #SoupMessageQueueItem and appends it to @queue.
  *
- * Return value: the new item, which you must unref with
+ * Returns: the new item, which you must unref with
  * soup_message_queue_unref_item() when you are done with.
  **/
 SoupMessageQueueItem *
@@ -203,7 +203,7 @@ soup_message_queue_item_unref (SoupMessageQueueItem *item)
  * the item with soup_message_queue_unref_item() when you are done
  * with it.
  *
- * Return value: (nullable): the queue item for @msg, or %NULL
+ * Returns: (nullable): the queue item for @msg, or %NULL
  **/ 
 SoupMessageQueueItem *
 soup_message_queue_lookup (SoupMessageQueue *queue, SoupMessage *msg)
@@ -233,7 +233,7 @@ soup_message_queue_lookup (SoupMessageQueue *queue, SoupMessage *msg)
  * only need to unref the item yourself if you are not going to
  * finishing walking the queue.)
  *
- * Return value: the first item in @queue.
+ * Returns: the first item in @queue.
  **/ 
 SoupMessageQueueItem *
 soup_message_queue_first (SoupMessageQueue *queue)
@@ -263,7 +263,7 @@ soup_message_queue_first (SoupMessageQueue *queue)
  * yourself with soup_message_queue_unref_item() if you do not finish
  * walking the queue.
  *
- * Return value: the next item in @queue.
+ * Returns: the next item in @queue.
  **/ 
 SoupMessageQueueItem *
 soup_message_queue_next (SoupMessageQueue *queue, SoupMessageQueueItem *item)
diff --git a/libsoup/soup-message.c b/libsoup/soup-message.c
index 169c56fc..fbcf4f5d 100644
--- a/libsoup/soup-message.c
+++ b/libsoup/soup-message.c
@@ -778,7 +778,7 @@ soup_message_class_init (SoupMessageClass *message_class)
  * 
  * Creates a new empty #SoupMessage, which will connect to @uri
  *
- * Return value: (nullable): the new #SoupMessage (or %NULL if @uri
+ * Returns: (nullable): the new #SoupMessage (or %NULL if @uri
  * could not be parsed).
  */
 SoupMessage *
@@ -810,7 +810,7 @@ soup_message_new (const char *method, const char *uri_string)
  * 
  * Creates a new empty #SoupMessage, which will connect to @uri
  *
- * Return value: the new #SoupMessage
+ * Returns: the new #SoupMessage
  */
 SoupMessage *
 soup_message_new_from_uri (const char *method, GUri *uri)
@@ -1109,7 +1109,7 @@ header_handler_metamarshal (GClosure *closure, GValue *return_value,
  * incoming messages headers (that is, the <literal>request_headers</literal>)
  * contain a header named @header.
  *
- * Return value: the handler ID from g_signal_connect()
+ * Returns: the handler ID from g_signal_connect()
  **/
 guint
 soup_message_add_header_handler (SoupMessage *msg,
@@ -1168,7 +1168,7 @@ status_handler_metamarshal (GClosure *closure, GValue *return_value,
  * @signal must be a signal that will be emitted after @msg's status
  * is set (this means it can't be a "wrote" signal).
  *
- * Return value: the handler ID from g_signal_connect()
+ * Returns: the handler ID from g_signal_connect()
  **/
 guint
 soup_message_add_status_code_handler (SoupMessage *msg,
@@ -1424,7 +1424,7 @@ soup_message_set_flags (SoupMessage *msg, SoupMessageFlags flags)
  *
  * Gets the flags on @msg
  *
- * Return value: the flags
+ * Returns: the flags
  **/
 SoupMessageFlags
 soup_message_get_flags (SoupMessage *msg)
@@ -1527,7 +1527,7 @@ soup_message_set_http_version (SoupMessage *msg, SoupHTTPVersion version)
  * Gets the HTTP version of @msg. This is the minimum of the
  * version from the request and the version from the response.
  *
- * Return value: the HTTP version
+ * Returns: the HTTP version
  **/
 SoupHTTPVersion
 soup_message_get_http_version (SoupMessage *msg)
@@ -1549,7 +1549,7 @@ soup_message_get_http_version (SoupMessage *msg)
  * further requests after processing @msg, based on the HTTP version,
  * Connection header, etc.
  *
- * Return value: %TRUE or %FALSE.
+ * Returns: %TRUE or %FALSE.
  **/
 gboolean
 soup_message_is_keepalive (SoupMessage *msg)
@@ -1618,7 +1618,7 @@ soup_message_set_uri (SoupMessage *msg, GUri *uri)
  *
  * Gets @msg's URI
  *
- * Return value: (transfer none): the URI @msg is targeted for.
+ * Returns: (transfer none): the URI @msg is targeted for.
  **/
 GUri *
 soup_message_get_uri (SoupMessage *msg)
@@ -2012,7 +2012,7 @@ soup_message_set_priority (SoupMessage        *msg,
  * Retrieves the #SoupMessagePriority. If not set this value defaults
  * to #SOUP_MESSAGE_PRIORITY_NORMAL.
  *
- * Return value: the priority of the message.
+ * Returns: the priority of the message.
  *
  */
 SoupMessagePriority
diff --git a/libsoup/soup-misc.c b/libsoup/soup-misc.c
index c9ae39cd..641d1281 100644
--- a/libsoup/soup-misc.c
+++ b/libsoup/soup-misc.c
@@ -19,7 +19,7 @@
  *
  * Hashes @key in a case-insensitive manner.
  *
- * Return value: the hash code.
+ * Returns: the hash code.
  **/
 guint
 soup_str_case_hash (gconstpointer key)
@@ -41,7 +41,7 @@ soup_str_case_hash (gconstpointer key)
  *
  * Compares @v1 and @v2 in a case-insensitive manner
  *
- * Return value: %TRUE if they are equal (modulo case)
+ * Returns: %TRUE if they are equal (modulo case)
  **/
 gboolean
 soup_str_case_equal (gconstpointer v1,
@@ -180,7 +180,7 @@ const char soup_char_attributes[] = {
  *
  * Checks if the @host and @compare_with exactly match or prefixed with a dot.
  *
- * Return value: %TRUE if the hosts match, %FALSE otherwise
+ * Returns: %TRUE if the hosts match, %FALSE otherwise
  *
  **/
 gboolean
diff --git a/libsoup/soup-multipart-input-stream.c b/libsoup/soup-multipart-input-stream.c
index 571434f1..68fbac52 100644
--- a/libsoup/soup-multipart-input-stream.c
+++ b/libsoup/soup-multipart-input-stream.c
@@ -463,7 +463,7 @@ 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: (nullable) (transfer full): a new #GInputStream, or
+ * Returns: (nullable) (transfer full): a new #GInputStream, or
  * %NULL if there are no more parts
  *
  */
@@ -556,7 +556,7 @@ soup_multipart_input_stream_next_part_async (SoupMultipartInputStream *multipart
  *
  * Finishes an asynchronous request for the next part.
  *
- * Return value: (nullable) (transfer full): a newly created
+ * Returns: (nullable) (transfer full): a newly created
  * #GInputStream for reading the next part or %NULL if there are no
  * more parts.
  *
@@ -585,7 +585,7 @@ 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: (nullable) (transfer none): a #SoupMessageHeaders
+ * Returns: (nullable) (transfer none): a #SoupMessageHeaders
  * containing the headers for the part currently being processed or
  * %NULL if the headers failed to parse.
  *
diff --git a/libsoup/soup-multipart.c b/libsoup/soup-multipart.c
index a0f8a216..ddb634a9 100644
--- a/libsoup/soup-multipart.c
+++ b/libsoup/soup-multipart.c
@@ -83,7 +83,7 @@ generate_boundary (void)
  * boundary string. Note that @mime_type must be the full MIME type,
  * including "multipart/".
  * 
- * Return value: a new empty #SoupMultipart of the given @mime_type
+ * Returns: a new empty #SoupMultipart of the given @mime_type
  *
  * See also: soup_message_new_from_multipart()
  **/
@@ -127,7 +127,7 @@ find_boundary (const char *start, const char *end,
  *
  * Parses @headers and @body to form a new #SoupMultipart
  *
- * Return value: (nullable): a new #SoupMultipart (or %NULL if the
+ * Returns: (nullable): a new #SoupMultipart (or %NULL if the
  * message couldn't be parsed or wasn't multipart).
  *
  **/
@@ -225,7 +225,7 @@ soup_multipart_new_from_message (SoupMessageHeaders *headers,
  *
  * Gets the number of body parts in @multipart
  *
- * Return value: the number of body parts in @multipart
+ * Returns: the number of body parts in @multipart
  *
  **/
 int
@@ -245,7 +245,7 @@ soup_multipart_get_length (SoupMultipart *multipart)
  *
  * Gets the indicated body part from @multipart.
  *
- * Return value: %TRUE on success, %FALSE if @part is out of range (in
+ * Returns: %TRUE on success, %FALSE if @part is out of range (in
  * which case @headers and @body won't be set)
  *
  **/
diff --git a/libsoup/soup-session-feature.c b/libsoup/soup-session-feature.c
index d23c8f2e..00082f7f 100644
--- a/libsoup/soup-session-feature.c
+++ b/libsoup/soup-session-feature.c
@@ -128,7 +128,7 @@ soup_session_feature_request_unqueued (SoupSessionFeature *feature,
  * different types. Eg, the authentication manager can be extended
  * with subtypes of #SoupAuth.
  *
- * Return value: %TRUE if @feature accepted @type as a subfeature.
+ * Returns: %TRUE if @feature accepted @type as a subfeature.
  *
  */
 gboolean
@@ -152,7 +152,7 @@ soup_session_feature_add_feature (SoupSessionFeature *feature,
  * Removes the "sub-feature" of type @type from the base feature
  * @feature. See soup_session_feature_add_feature().
  *
- * Return value: %TRUE if @type was removed from @feature
+ * Returns: %TRUE if @type was removed from @feature
  *
  */
 gboolean
@@ -176,7 +176,7 @@ soup_session_feature_remove_feature (SoupSessionFeature *feature,
  * Tests if @feature has a "sub-feature" of type @type. See
  * soup_session_feature_add_feature().
  *
- * Return value: %TRUE if @feature has a subfeature of type @type
+ * Returns: %TRUE if @feature has a subfeature of type @type
  *
  */
 gboolean
diff --git a/libsoup/soup-session.c b/libsoup/soup-session.c
index 8ea60172..37db0cdc 100644
--- a/libsoup/soup-session.c
+++ b/libsoup/soup-session.c
@@ -562,7 +562,7 @@ soup_session_get_property (GObject *object, guint prop_id,
  *
  * Creates a #SoupSession with the default options.
  *
- * Return value: the new session.
+ * Returns: the new session.
  *
  */
 SoupSession *
@@ -578,7 +578,7 @@ soup_session_new (void)
  *
  * Creates a #SoupSession with the specified options.
  *
- * Return value: the new session.
+ * Returns: the new session.
  *
  */
 SoupSession *
@@ -811,7 +811,7 @@ soup_session_requeue_item (SoupSession          *session,
  * If @msg has already been redirected too many times, this will
  * cause it to fail with %SOUP_STATUS_TOO_MANY_REDIRECTS.
  *
- * Return value: %TRUE if a redirection was applied, %FALSE if not
+ * Returns: %TRUE if a redirection was applied, %FALSE if not
  * (eg, because there was no Location header, or it could not be
  * parsed).
  *
@@ -1991,7 +1991,7 @@ soup_session_remove_feature_by_type (SoupSession *session, GType feature_type)
  * be the type of either a #SoupSessionFeature, or else a subtype of
  * some class managed by another feature, such as #SoupAuth).
  *
- * Return value: %TRUE or %FALSE
+ * Returns: %TRUE or %FALSE
  *
  **/
 gboolean
@@ -2029,7 +2029,7 @@ soup_session_has_feature (SoupSession *session,
  * you want to see all features, you can pass %SOUP_TYPE_SESSION_FEATURE
  * for @feature_type.)
  *
- * Return value: (transfer container) (element-type Soup.SessionFeature):
+ * Returns: (transfer container) (element-type Soup.SessionFeature):
  * a list of features. You must free the list, but not its contents
  *
  **/
@@ -2058,7 +2058,7 @@ 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: (nullable) (transfer none): a #SoupSessionFeature, or
+ * Returns: (nullable) (transfer none): a #SoupSessionFeature, or
  * %NULL. The feature is owned by @session.
  *
  **/
@@ -2104,7 +2104,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: (nullable) (transfer none): a #SoupSessionFeature, or %NULL. The
+ * Returns: (nullable) (transfer none): a #SoupSessionFeature, or %NULL. The
  * feature is owned by @session.
  *
  **/
@@ -2881,7 +2881,7 @@ soup_session_send_async (SoupSession         *session,
  * successful), returns a #GInputStream that can be used to read the
  * response body.
  *
- * Return value: (transfer full): a #GInputStream for reading the
+ * Returns: (transfer full): a #GInputStream for reading the
  *   response body, or %NULL on error.
  *
  */
@@ -2937,7 +2937,7 @@ soup_session_send_finish (SoupSession   *session,
  * soup_session_send() will only return once a final response has been
  * received.
  *
- * Return value: (transfer full): a #GInputStream for reading the
+ * Returns: (transfer full): a #GInputStream for reading the
  *   response body, or %NULL on error.
  *
  */
@@ -3563,7 +3563,7 @@ steal_connection (SoupSession          *session,
  * Calling this function may cause @msg to be freed if you are not
  * holding any other reference to it.
  *
- * Return value: (transfer full): the #GIOStream formerly associated
+ * Returns: (transfer full): the #GIOStream formerly associated
  *   with @msg (or %NULL if @msg was no longer associated with a
  *   connection). No guarantees are made about what kind of #GIOStream
  *   is returned.
@@ -3747,7 +3747,7 @@ soup_session_websocket_connect_async (SoupSession          *session,
  * returns a #SoupWebsocketConnection that can be used to communicate
  * with the server.
  *
- * Return value: (transfer full): a new #SoupWebsocketConnection, or
+ * Returns: (transfer full): a new #SoupWebsocketConnection, or
  *   %NULL on error.
  *
  */
diff --git a/libsoup/soup-status.c b/libsoup/soup-status.c
index 861d3d61..c1ab141f 100644
--- a/libsoup/soup-status.c
+++ b/libsoup/soup-status.c
@@ -26,7 +26,7 @@
  *
  * Tests if @status is an Informational (1xx) response.
  *
- * Return value: %TRUE or %FALSE
+ * Returns: %TRUE or %FALSE
  **/
 /**
  * SOUP_STATUS_IS_SUCCESSFUL:
@@ -34,7 +34,7 @@
  *
  * Tests if @status is a Successful (2xx) response.
  *
- * Return value: %TRUE or %FALSE
+ * Returns: %TRUE or %FALSE
  **/
 /**
  * SOUP_STATUS_IS_REDIRECTION:
@@ -42,7 +42,7 @@
  *
  * Tests if @status is a Redirection (3xx) response.
  *
- * Return value: %TRUE or %FALSE
+ * Returns: %TRUE or %FALSE
  **/
 /**
  * SOUP_STATUS_IS_CLIENT_ERROR:
@@ -50,7 +50,7 @@
  *
  * Tests if @status is a Client Error (4xx) response.
  *
- * Return value: %TRUE or %FALSE
+ * Returns: %TRUE or %FALSE
  **/
 /**
  * SOUP_STATUS_IS_SERVER_ERROR:
@@ -58,7 +58,7 @@
  *
  * Tests if @status is a Server Error (5xx) response.
  *
- * Return value: %TRUE or %FALSE
+ * Returns: %TRUE or %FALSE
  **/
 
 /**
@@ -232,7 +232,7 @@ static const struct {
  * Instead, you should create you own error messages based on the
  * status code, and on what you were trying to do.
  *
- * Return value: the (terse, English) description of @status_code
+ * Returns: the (terse, English) description of @status_code
  **/
 const char *
 soup_status_get_phrase (guint status_code)
diff --git a/libsoup/websocket/soup-websocket-extension.c b/libsoup/websocket/soup-websocket-extension.c
index 3120ab76..fb75f7cd 100644
--- a/libsoup/websocket/soup-websocket-extension.c
+++ b/libsoup/websocket/soup-websocket-extension.c
@@ -80,7 +80,7 @@ soup_websocket_extension_class_init (SoupWebsocketExtensionClass *auth_class)
  *
  * Configures @extension with the given @params
  *
- * Return value: %TRUE if extension could be configured with the given parameters, or %FALSE otherwise
+ * Returns: %TRUE if extension could be configured with the given parameters, or %FALSE otherwise
  */
 gboolean
 soup_websocket_extension_configure (SoupWebsocketExtension     *extension,