Add Doxygen documentation for public API.

2 files changed, 162 insertions, 7 deletions

diff --git a/lib/include/radsec/radsec.h b/lib/include/radsec/radsec.h
index 971fc17..66c55f3 100644
--- a/lib/include/radsec/radsec.h
+++ b/lib/include/radsec/radsec.h
@@ -1,5 +1,6 @@
-/** @file libradsec.h
-    @brief Header file for libradsec.  */
+/** \file radsec.h
+    \brief Public interface for libradsec.  */
+
 /* See the file COPYING for licensing information.  */
 
 #include <unistd.h>
@@ -83,70 +84,197 @@ struct rs_conn_callbacks {
 
 
 /* Function prototypes.  */
+
+/*************/
 /* Context.  */
+/*************/
+/** Create a context.  Freed by calling \a rs_context_destroy.  Note
+    that the context must not be freed before all other libradsec
+    objects have been freed.
+
+    \a ctx Address of pointer to a struct rs_context.  This is the output.
+
+    \a dict Name of a FreeRADIUS dictionary.
+
+    \return RSE_OK (0) on success, RSE_NOMEM on out of memory or
+    RSE_FR on FreeRADIUS initialization error.  */
 int rs_context_create(struct rs_context **ctx, const char *dict);
+
+/** Free a context.  Note that the context must not be freed before
+    all other libradsec objects have been freed.  */
 void rs_context_destroy(struct rs_context *ctx);
+
+/** Set allocation scheme to use.  \a scheme is the allocation scheme
+    to use, see \a rs_alloc_scheme.  \return On success, RSE_OK (0) is
+    returned.  On error, !0 is returned and a struct \a rs_error is
+    pushed on the error stack for the context.  The error can be
+    accessed using \a rs_err_ctx_pop.  */
 int rs_context_set_alloc_scheme(struct rs_context *ctx,
 				struct rs_alloc_scheme *scheme);
+
+/** Read configuration file. \a config_file is the path of the
+    configuration file to read.  \return On success, RSE_OK (0) is
+    returned.  On error, !0 is returned and a struct \a rs_error is
+    pushed on the error stack for the context.  The error can be
+    accessed using \a rs_err_ctx_pop.  */
 int rs_context_read_config(struct rs_context *ctx, const char *config_file);
 
+/****************/
 /* Connection.  */
+/****************/
+/** Create a connection.  \a conn is the address of a pointer to an \a
+    rs_connection, the output.  Free the connection using \a
+    rs_conn_destroy.  Note that a connection must not be freed before
+    all packets associated with the connection have been freed.  A
+    packet is associated with a connection when it's created (\a
+    rs_packet_create) or received (\a rs_conn_receive_packet).
+
+    If \a config is not NULL it should be the name of a configuration
+    found in the config file read in using \a rs_context_read_config.
+    \return On success, RSE_OK (0) is returned.  On error, !0 is
+    returned and a struct \a rs_error is pushed on the error stack for
+    the context.  The error can be accessed using \a
+    rs_err_ctx_pop.  */
 int rs_conn_create(struct rs_context *ctx,
 		   struct rs_connection **conn,
 		   const char *config);
-void rs_conn_set_type(struct rs_connection *conn, rs_conn_type_t type);
+
+/** Not implemented.  */
 int rs_conn_add_listener(struct rs_connection *conn,
 			 rs_conn_type_t type,
 			 const char *hostname,
 			 int port);
+/** Disconnect connection \a conn.  \return RSE_OK (0) on success, !0
+ * on error.  On error, errno is set appropriately.  */
 int rs_conn_disconnect (struct rs_connection *conn);
+
+/** Disconnect and free memory allocated for connection \a conn.  Note
+    that a connection must not be freed before all packets associated
+    with the connection have been freed.  A packet is associated with
+    a connection when it's created (\a rs_packet_create) or received
+    (\a rs_conn_receive_packet).  \return RSE_OK (0) on success, !0 *
+    on error.  On error, errno is set appropriately. */
 int rs_conn_destroy(struct rs_connection *conn);
+
+/** Set connection type for \a conn.  */
+void rs_conn_set_type(struct rs_connection *conn, rs_conn_type_t type);
+
+/** Not implemented.  */
 int rs_conn_set_eventbase(struct rs_connection *conn, struct event_base *eb);
+
+/** Register callbacks \a cb for connection \a conn.  */
 void rs_conn_set_callbacks(struct rs_connection *conn,
 			   struct rs_conn_callbacks *cb);
+
+/** Remove callbacks for connection \a conn.  */
 void rs_conn_del_callbacks(struct rs_connection *conn);
+
+/** Return callbacks registered for connection \a conn.  \return
+    Installed callbacks are returned.  */
 struct rs_conn_callbacks *rs_conn_get_callbacks(struct rs_connection *conn);
+
+/** Not implemented.  */
 int rs_conn_select_peer(struct rs_connection *conn, const char *name);
+
+/** Not implemented.  */
 int rs_conn_get_current_peer(struct rs_connection *conn,
 			     const char *name,
 			     size_t buflen);
+
+/** Special function used in blocking mode, i.e. with no callbacks
+    registered.  For any other use of libradsec, a \a received_cb
+    callback should be registered using \a rs_conn_set_callbacks.
+
+    If \a req_msg is not NULL, a successfully received RADIUS message
+    is verified against it.  If \a pkt_out is not NULL it will upon
+    return contain a pointer to an \a rs_packet containing the new
+    message.
+
+    \return On error or if the connect (TCP only) or read times out,
+    \a pkt_out will not be changed and one or more errors are pushed
+    on \a conn (available through \a rs_err_conn_pop).  */
 int rs_conn_receive_packet(struct rs_connection *conn,
 			   struct rs_packet *request,
 			   struct rs_packet **pkt_out);
+
+/** Get the file descriptor associated with connection \a conn.
+ * \return File descriptor.  */
 int rs_conn_fd(struct rs_connection *conn);
+
+/** Set the timeout value for connection \a conn.  */
 void rs_conn_set_timeout(struct rs_connection *conn, struct timeval *tv);
 
 /* Peer -- client and server.  */
 int rs_peer_create(struct rs_connection *conn, struct rs_peer **peer_out);
-int rs_peer_set_address(struct rs_peer *peer, const char *hostname,
+int rs_peer_set_address(struct rs_peer *peer,
+			const char *hostname,
 			const char *service);
 int rs_peer_set_secret(struct rs_peer *peer, const char *secret);
 void rs_peer_set_timeout(struct rs_peer *peer, int timeout);
 void rs_peer_set_retries(struct rs_peer *peer, int retries);
 
+/************/
 /* Packet.  */
+/************/
+/** Create a packet associated with connection \a conn.  */
 int rs_packet_create(struct rs_connection *conn, struct rs_packet **pkt_out);
+
+/** Free all memory allocated for packet \a pkt.  */
 void rs_packet_destroy(struct rs_packet *pkt);
+
+/** Add attribute \a attr to packet \a pkt.  */
 void rs_packet_add_attr(struct rs_packet *pkt, struct rs_attr *attr);
+
+/** Send packet \a pkt on the connection associated with \a pkt.  \a
+    user_data is sent to the \a rs_conn_packet_received_cb callback
+    registered with the connection.  If no callback is registered with
+    the connection, the event loop is run by \a rs_packet_send and it
+    blocks until the packet has been succesfully sent.
+
+    \return On success, RSE_OK (0) is returned.  On error, !0 is
+    returned and a struct \a rs_error is pushed on the error stack for
+    the connection.  The error can be accessed using \a
+    rs_err_conn_pop.  */
 int rs_packet_send(struct rs_packet *pkt, void *user_data);
+
+/** Return the FreeRADIUS packet associated with packet \a pkt.  */
 struct radius_packet *rs_packet_frpkt(struct rs_packet *pkt);
+
+/** Create a RADIUS authentication request packet associated with
+    connection \a conn.  Optionally, User-Name and User-Password
+    attributes are added to the packet using the data in \a user_name
+    and \a user_pw.  */
 int rs_packet_create_authn_request(struct rs_connection *conn,
 				   struct rs_packet **pkt,
 				   const char *user_name,
 				   const char *user_pw);
 
+/***************/
 /* Attribute.  */
+/***************/
 /* FIXME: Replace (or complement) with a wrapper for paircreate().  */
+/** Create a RADIUS attribute of type \a type and with the value \a
+    val.  */
 int rs_attr_create(struct rs_connection *conn,
 		   struct rs_attr **attr,
 		   const char *type,
 		   const char *val);
+/** Free memory for RADIUS attribute \a attr.  */
 void rs_attr_destroy(struct rs_attr *attr);
 
+/************/
 /* Config.  */
+/************/
+/** Find the realm named \a name in the configuration file previoiusly
+    read in using \a rs_context_read_config.  */
 struct rs_realm *rs_conf_find_realm(struct rs_context *ctx, const char *name);
 
+/***********/
 /* Error.  */
+/***********/
+/** Create a struct \a rs_error and push it on a FIFO associated with
+    context \a ctx.  Note: The depth of the error stack is one (1) at
+    the moment.  This will change in a future release.  */
 int rs_err_ctx_push(struct rs_context *ctx, int code, const char *fmt, ...);
 int rs_err_ctx_push_fl(struct rs_context *ctx,
 		       int code,
@@ -154,7 +282,13 @@ int rs_err_ctx_push_fl(struct rs_context *ctx,
 		       int line,
 		       const char *fmt,
 		       ...);
+/** Pop the first error from the error FIFO associated with context \a
+    ctx or NULL if there are no errors in the FIFO.  */
 struct rs_error *rs_err_ctx_pop(struct rs_context *ctx);
+
+/** Create a struct \a rs_error and push it on a FIFO associated with
+    connection \a conn.  Note: The depth of the error stack is one (1)
+    at the moment.  This will change in a future release.  */
 int rs_err_conn_push(struct rs_connection *conn,
 		     int code,
 		     const char *fmt,
@@ -165,7 +299,10 @@ int rs_err_conn_push_fl(struct rs_connection *conn,
 			int line,
 			const char *fmt,
 			...);
+/** Pop the first error from the error FIFO associated with connection
+    \a conn or NULL if there are no errors in the FIFO.  */
 struct rs_error *rs_err_conn_pop(struct rs_connection *conn);
+
 int rs_err_conn_peek_code (struct rs_connection *conn);
 void rs_err_free(struct rs_error *err);
 char *rs_err_msg(struct rs_error *err);
diff --git a/lib/include/radsec/request.h b/lib/include/radsec/request.h
index 4a540bd..ef422b5 100644
--- a/lib/include/radsec/request.h
+++ b/lib/include/radsec/request.h
@@ -1,3 +1,6 @@
+/** \file request.h
+    \brief Public interface for libradsec request's.  */
+
 /* See the file COPYING for licensing information.  */
 
 struct rs_request;
@@ -6,15 +9,30 @@ struct rs_request;
 extern "C" {
 #endif
 
+/** Create a request associated with connection \a conn.  */
 int rs_request_create(struct rs_connection *conn, struct rs_request **req_out);
-void rs_request_add_reqpkt(struct rs_request *req, struct rs_packet *reqpkt);
+/** Add RADIUS request message \a req_msg to request \a req.  */
+void rs_request_add_reqpkt(struct rs_request *req, struct rs_packet *req_msg);
 
+/** Create a request associated with connection \a conn containing a
+    RADIUS authentication message with \a user_name and \a user_pw
+    attributes.  \a user_name and _user_pw are optional and can be
+    NULL.  */
 int rs_request_create_authn(struct rs_connection *conn,
 			    struct rs_request **req_out,
 			    const char *user_name,
 			    const char *user_pw);
-int rs_request_send(struct rs_request *request, struct rs_packet **resp_msg);
-void rs_request_destroy(struct rs_request *request);
+/** Send request \a req and wait for a matching response.  The
+    response is put in \a resp_msg (if not NULL).  NOTE: At present,
+    no more than one outstanding request to a given realm is
+    supported.  This will change in a future version.  */
+int rs_request_send(struct rs_request *req, struct rs_packet **resp_msg);
+
+/** Free all memory allocated by request \a req including the request
+    packet and any response package associated with the request.  Note
+    that a request must be freed before its associated connection can
+    be freed.  */
+void rs_request_destroy(struct rs_request *req);
 
 #if defined (__cplusplus)
 }