[librest/wip/baedert/tests: 4/22] RestProxyCall: Fix various docs

[Timm Bäder <baedert src gnome org>]

commit ffafeef32e9533ea4541dddeffae79b3846297f1
Author: Timm Bäder <mail baedert org>
Date:   Thu Jul 21 23:19:47 2016 +0200

    RestProxyCall: Fix various docs
    
    Add appropriate transfer and nullability annotations.

 rest/rest-proxy-call.c |   52 ++++++++++++++++++++++++++++++-----------------
 1 files changed, 33 insertions(+), 19 deletions(-)
---
diff --git a/rest/rest-proxy-call.c b/rest/rest-proxy-call.c
index aac7806..ecbcd90 100644
--- a/rest/rest-proxy-call.c
+++ b/rest/rest-proxy-call.c
@@ -220,13 +220,10 @@ rest_proxy_call_set_method (RestProxyCall *call,
   RestProxyCallPrivate *priv = GET_PRIVATE (call);
 
   g_return_if_fail (REST_IS_PROXY_CALL (call));
+  g_return_if_fail (method != NULL);
 
   g_free (priv->method);
-
-  if (method)
-    priv->method = g_strdup (method);
-  else
-    priv->method = g_strdup ("GET");
+  priv->method = g_strdup (method);
 }
 
 /**
@@ -234,6 +231,9 @@ rest_proxy_call_set_method (RestProxyCall *call,
  * @call: The #RestProxyCall
  *
  * Get the HTTP method to use when making the call, for example GET or POST.
+ *
+ * Returns: (nullable) (transfer none): The method of @call.
+ *   This value is owned by @call and may not be modified or freed.
  */
 const char *
 rest_proxy_call_get_method (RestProxyCall *call)
@@ -246,7 +246,7 @@ rest_proxy_call_get_method (RestProxyCall *call)
 /**
  * rest_proxy_call_set_function:
  * @call: The #RestProxyCall
- * @function: The function to call
+ * @function: (nullable): The function to call or %NULL
  *
  * Set the REST "function" to call on the proxy.  This is appended to the URL,
  * so that for example a proxy with the URL
@@ -272,9 +272,10 @@ rest_proxy_call_set_function (RestProxyCall *call,
  *
  * Get the REST function that is going to be called on the proxy.
  *
- * Returns: The REST "function" for the current call, see also
- * rest_proxy_call_set_function(). This string is owned by the #RestProxyCall
- * and should not be freed.
+ * Returns: (transfer none) (nullable): The REST "function" for the current call, see also
+ *   rest_proxy_call_set_function() or %NULL if no function has been set yey.
+ *   This string is owned by the #RestProxyCall and should not be freed.
+ *
  * Since: 0.7.92
  */
 const char *
@@ -303,6 +304,8 @@ rest_proxy_call_add_header (RestProxyCall *call,
   RestProxyCallPrivate *priv = GET_PRIVATE (call);
 
   g_return_if_fail (REST_IS_PROXY_CALL (call));
+  g_return_if_fail (header != NULL);
+  g_return_if_fail (value != NULL);
 
   g_hash_table_insert (priv->headers,
                        g_strdup (header),
@@ -362,14 +365,16 @@ rest_proxy_call_add_headers_from_valist (RestProxyCall *call,
  *
  * Get the value of the header called @header.
  *
- * Returns: The header value, or %NULL if it does not exist. This string is
- * owned by the #RestProxyCall and should not be freed.
+ * Returns: (transfer none) (nullable): The header value, or %NULL
+ *   if it does not exist. This string is
+ *   owned by the #RestProxyCall and should not be freed.
  */
 const gchar *
 rest_proxy_call_lookup_header (RestProxyCall *call,
                                const gchar   *header)
 {
   g_return_val_if_fail (REST_IS_PROXY_CALL (call), NULL);
+  g_return_val_if_fail (header != NULL, NULL);
 
   return g_hash_table_lookup (GET_PRIVATE (call)->headers, header);
 }
@@ -386,6 +391,7 @@ rest_proxy_call_remove_header (RestProxyCall *call,
                                const gchar   *header)
 {
   g_return_if_fail (REST_IS_PROXY_CALL (call));
+  g_return_if_fail (header != NULL);
 
   g_hash_table_remove (GET_PRIVATE (call)->headers, header);
 }
@@ -409,6 +415,8 @@ rest_proxy_call_add_param (RestProxyCall *call,
   RestParam *param;
 
   g_return_if_fail (REST_IS_PROXY_CALL (call));
+  g_return_if_fail (name != NULL);
+  g_return_if_fail (value != NULL);
 
   param = rest_param_new_string (name, REST_MEMORY_COPY, value);
   rest_params_add (priv->params, param);
@@ -475,14 +483,16 @@ rest_proxy_call_add_params_from_valist (RestProxyCall *call,
  *
  * Get the value of the parameter called @name.
  *
- * Returns: The parameter value, or %NULL if it does not exist. This string is
- * owned by the #RestProxyCall and should not be freed.
+ * Returns: (transfer none) (nullable): The parameter value,
+ *   or %NULL if it does not exist. This string is
+ *   owned by the #RestProxyCall and should not be freed.
  */
 RestParam *
 rest_proxy_call_lookup_param (RestProxyCall *call,
                               const gchar   *name)
 {
   g_return_val_if_fail (REST_IS_PROXY_CALL (call), NULL);
+  g_return_val_if_fail (name != NULL, NULL);
 
   return rest_params_get (GET_PRIVATE (call)->params, name);
 }
@@ -499,6 +509,7 @@ rest_proxy_call_remove_param (RestProxyCall *call,
                               const gchar   *name)
 {
   g_return_if_fail (REST_IS_PROXY_CALL (call));
+  g_return_if_fail (name != NULL);
 
   rest_params_remove (GET_PRIVATE (call)->params, name);
 }
@@ -917,6 +928,8 @@ _call_message_call_completed_cb (SoupSession *session,
  *   cancel the call, or %NULL
  * @callback: (scope async): callback to call when the async call is finished
  * @user_data: (closure): user data for the callback
+ *
+ * Asynchronously invokes @call. Finish with rest_proxy_call_invoke_finish().
  */
 void
 rest_proxy_call_invoke_async (RestProxyCall      *call,
@@ -1259,7 +1272,7 @@ rest_proxy_call_lookup_response_header (RestProxyCall *call,
   RestProxyCallPrivate *priv = GET_PRIVATE (call);
 
   g_return_val_if_fail (REST_IS_PROXY_CALL (call), NULL);
-  g_return_val_if_fail (header != NULL);
+  g_return_val_if_fail (header != NULL, NULL);
 
   if (!priv->response_headers)
   {
@@ -1273,8 +1286,9 @@ rest_proxy_call_lookup_response_header (RestProxyCall *call,
  * rest_proxy_call_get_response_headers:
  * @call: The #RestProxyCall
  *
- * Returns: (transfer container): pointer to a hash table of
- * headers. This hash table must not be changed. You should call
+ * Returns: (transfer container) (nullable): pointer to a hash table of
+ * headers or %NULL if no response headers are present.
+ * This hash table must not be changed. You should call
  * g_hash_table_unref() when you have finished with it.
  */
 GHashTable *
@@ -1314,7 +1328,7 @@ rest_proxy_call_get_payload_length (RestProxyCall *call)
  *
  * Get the return payload.
  *
- * Returns: A pointer to the payload. This is owned by #RestProxyCall and should
+ * Returns: (transfer none): A pointer to the payload. This is owned by #RestProxyCall and should
  * not be freed.
  */
 const gchar *
@@ -1345,7 +1359,7 @@ rest_proxy_call_get_status_code (RestProxyCall *call)
  *
  * Get the human-readable HTTP status message for the call.
  *
- * Returns: The status message. This string is owned by #RestProxyCall and
+ * Returns: (transfer none): The status message. This string is owned by #RestProxyCall and
  * should not be freed.
  */
 const gchar *
@@ -1367,7 +1381,7 @@ rest_proxy_call_get_status_message (RestProxyCall *call)
  * Invoker for a virtual method to serialize the parameters for this
  * #RestProxyCall.
  *
- * Returns: TRUE if the serialization was successful, FALSE otherwise.
+ * Returns: %TRUE if the serialization was successful, %FALSE otherwise.
  */
 gboolean
 rest_proxy_call_serialize_params (RestProxyCall *call,