Document some obvious cases where a function might also return NULL

Closes: #525
(cherry picked from commit 808524252f888303e4e95f09c3f8c225ef08f096)

diff --git a/include/event2/dns.h b/include/event2/dns.h
index 17cd86a2ec2df91f515b056619e67a1ca2fca700..2025b9e67f9cb4aa7a7e43af29a797a40ae53e4c 100644 (file)
--- a/include/event2/dns.h
+++ b/include/event2/dns.h
@@ -615,7 +615,8 @@ typedef void (*evdns_request_callback_fn_type)(struct evdns_server_request *, vo
     @param callback A function to invoke whenever we get a DNS request
       on the socket.
     @param user_data Data to pass to the callback.
-    @return an evdns_server_port structure for this server port.
+    @return an evdns_server_port structure for this server port or NULL if
+      an error occurred.
  */
 EVENT2_EXPORT_SYMBOL
 struct evdns_server_port *evdns_add_server_port_with_base(struct event_base *base, evutil_socket_t socket, int flags, evdns_request_callback_fn_type callback, void *user_data);

diff --git a/include/event2/event.h b/include/event2/event.h
index 6e0a4f04c739649fd205406ffc6bf0589b243600..450bc33c8e4cf69ac8f6d26c7ff00c1805b8930b 100644 (file)
--- a/include/event2/event.h
+++ b/include/event2/event.h
@@ -1073,7 +1073,7 @@ void *event_self_cbarg(void);
   @param callback_arg an argument to be passed to the callback function
 
   @return a newly allocated struct event that must later be freed with
-    event_free().
+    event_free() or NULL if an error occurred.
   @see event_free(), event_add(), event_del(), event_assign()
  */
 EVENT2_EXPORT_SYMBOL

diff --git a/include/event2/http.h b/include/event2/http.h
index 8fb5642f7f483d63421e1048c52b785f8ead6c84..acee552082e430417ba5b8261254b87a2ffc2fa0 100644 (file)
--- a/include/event2/http.h
+++ b/include/event2/http.h
@@ -78,7 +78,8 @@ struct evdns_base;
  * Create a new HTTP server.
  *
  * @param base (optional) the event base to receive the HTTP events
- * @return a pointer to a newly initialized evhttp server structure
+ * @return a pointer to a newly initialized evhttp server structure or NULL
+ *   on error
  * @see evhttp_free()
  */
 EVENT2_EXPORT_SYMBOL
@@ -516,7 +517,8 @@ enum evhttp_request_kind { EVHTTP_REQUEST, EVHTTP_RESPONSE };
  *     when the connection closes.  It must have no fd set on it.
  * @param address the address to which to connect
  * @param port the port to connect to
- * @return an evhttp_connection object that can be used for making requests
+ * @return an evhttp_connection object that can be used for making requests or
+ *   NULL on error
  */
 EVENT2_EXPORT_SYMBOL
 struct evhttp_connection *evhttp_connection_base_bufferevent_new(
@@ -636,7 +638,8 @@ void evhttp_request_free(struct evhttp_request *req);
  *     specified host name resolution will block.
  * @param address the address to which to connect
  * @param port the port to connect to
- * @return an evhttp_connection object that can be used for making requests
+ * @return an evhttp_connection object that can be used for making requests or
+ *   NULL on error
  */
 EVENT2_EXPORT_SYMBOL
 struct evhttp_connection *evhttp_connection_base_new(

diff --git a/include/event2/http_compat.h b/include/event2/http_compat.h
index a9eb5972def3f5d105726e70920818212d4b1b20..794a581083e4e12dd9d48679cb06d89469e5e070 100644 (file)
--- a/include/event2/http_compat.h
+++ b/include/event2/http_compat.h
@@ -56,7 +56,8 @@ extern "C" {
  *
  * @param address the address to which the HTTP server should be bound
  * @param port the port number on which the HTTP server should listen
- * @return an struct evhttp object
+ * @return a pointer to a newly initialized evhttp server structure
+ *   or NULL on error
  */
 EVENT2_EXPORT_SYMBOL
 struct evhttp *evhttp_start(const char *address, ev_uint16_t port);

diff --git a/include/event2/rpc.h b/include/event2/rpc.h
index 9c55b51367fd2d431daa919bf9aff27a74bc6969..830d0c62b1e929e2efd7e25461bd338abe5c6745 100644 (file)
--- a/include/event2/rpc.h
+++ b/include/event2/rpc.h
@@ -292,7 +292,7 @@ struct evhttp;
 /** Creates a new rpc base from which RPC requests can be received
  *
  * @param server a pointer to an existing HTTP server
- * @return a newly allocated evrpc_base struct
+ * @return a newly allocated evrpc_base struct or NULL if an error occurred
  * @see evrpc_free()
  */
 EVENT2_EXPORT_SYMBOL
@@ -406,7 +406,8 @@ int evrpc_make_request(struct evrpc_request_wrapper *ctx);
  *
  * @param base a pointer to an struct event_based object; can be left NULL
  *   in singled-threaded applications
- * @return a newly allocated struct evrpc_pool object
+ * @return a newly allocated struct evrpc_pool object or NULL if an error
+ *   occurred
  * @see evrpc_pool_free()
  */
 EVENT2_EXPORT_SYMBOL
@@ -566,7 +567,8 @@ int evrpc_hook_find_meta(void *ctx, const char *key,
  * returns the connection object associated with the request
  *
  * @param ctx the context provided to the hook call
- * @return a pointer to the evhttp_connection object
+ * @return a pointer to the evhttp_connection object or NULL if an error
+ *   occurred
  */
 EVENT2_EXPORT_SYMBOL
 struct evhttp_connection *evrpc_hook_get_connection(void *ctx);