Document some obvious cases where a function might also return NULL

Closes: #525

5 files changed, 16 insertions, 9 deletions

diff --git a/include/event2/dns.h b/include/event2/dns.h
index 17cd86a2..2025b9e6 100644
--- 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 6e0a4f04..450bc33c 100644
--- 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 8fb5642f..acee5520 100644
--- 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 a9eb5972..794a5810 100644
--- 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 9c55b513..830d0c62 100644
--- 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);