Remove @version, doxygen seems to parse $id ok

Add callback docs for connection API

diff --git a/src/include/connection.h b/src/include/connection.h
index b72a2e99c691913153abd5fa75dc6bee9516d616..074f5d4a6418509126544fb459ec16810d97468b 100644 (file)
--- a/src/include/connection.h
+++ b/src/include/connection.h
@@ -15,12 +15,14 @@
  */
 #ifndef FR_CONNECTION_H
 #define FR_CONNECTION_H
-/**
+/* 
+ * $Id$
+ *
  * @file connection.h
  * @brief Structures, prototypes and global variables for server connection pools.
  *
- * @version $Id$
- * @copyright 1999,2000,2002,2003,2004,2005,2006,2007,2008  The FreeRADIUS server project
+ * @copyright 2012  The FreeRADIUS server project
+ * @copyright 2012  Alan DeKok <aland@deployingradius.com>
  */
  
 #include <freeradius-devel/ident.h>
@@ -34,8 +36,40 @@ extern "C" {
 
 typedef struct fr_connection_pool_t fr_connection_pool_t;
 
+/** Create a new connection handle
+ *
+ * This function will be called whenever the connection pool manager needs
+ * to spawn a new connection, and on reconnect.
+ *
+ * @note A function pointer matching this prototype must be passed
+ * to fr_connection_pool.
+ * @param[in] ctx pointer passed to fr_connection_pool_init.
+ * @return NULL on error, else a connection handle.
+ */
 typedef void *(*fr_connection_create_t)(void *ctx);
+
+/** Check a connection handle is still viable
+ *
+ * Should check the state  of a connection handle.
+ *
+ * @note NULL may be passed to fr_connection_init, if there is no way to check
+ * the state of a connection handle.
+ * @note Not currently use by connection pool manager.
+ * @param[in] ctx pointer passed to fr_connection_pool_init.
+ * @param[in] connection handle returned by fr_connection_create_t.
+ * @return < 0 on error or if the connection is unusable, else 0.
+ */
 typedef int (*fr_connection_alive_t)(void *ctx, void *connection);
+
+/** Delete a connection and free allocated memory
+ *
+ * Should close any sockets associated with the passed connection handle,
+ * and free any memory allocated to it.
+ *
+ * @param[in] ctx pointer passed to fr_connection_pool_init.
+ * @param[in,out] connection handle returned by fr_connection_create_t.
+ * @return < 0 on error else 0 if connection was closed successfully.
+ */
 typedef int (*fr_connection_delete_t)(void *ctx, void *connection);
 
 fr_connection_pool_t *fr_connection_pool_init(CONF_SECTION *cs,

diff --git a/src/include/libradius.h b/src/include/libradius.h
index c2eeeddba68f3d8f370399a9f187eb8510d2e57f..ee5567f69d1b48a30b21b3d36f08d1ce4c4f8233 100644 (file)
--- a/src/include/libradius.h
+++ b/src/include/libradius.h
@@ -16,11 +16,12 @@
 #ifndef LIBRADIUS_H
 #define LIBRADIUS_H
 /*
+ * $Id$
+ *
  * @file libradius.h
  * @brief Structures and prototypes for the radius library.
  *
- * @version $Id$
- * @copyright 1999,2000,2001,2002,2003,2004,2005,2006,2007,2008  The FreeRADIUS server project
+ * @copyright 1999-2008 The FreeRADIUS server project
  */
 
 #include <freeradius-devel/ident.h>

diff --git a/src/include/md5.h b/src/include/md5.h
index 380cbc9480efcd882d9f5f4d1b84a3d4b5608855..3002d118d38158cccadded18f875d55e83121e84 100644 (file)
--- a/src/include/md5.h
+++ b/src/include/md5.h
@@ -1,8 +1,9 @@
 /*
+ * $Id$
+ *
  * @file md5.h
  * @brief Structures and prototypes for md5.
  *
- * @version $Id$
  * @license LGPL, but largely derived from a public domain source.
  */
 

diff --git a/src/include/modules.h b/src/include/modules.h
index a9a5daae2bc91e62e86746ed8edda6b39969744c..c306d681fed1f33337334bf7e42855ae1d33f652 100644 (file)
--- a/src/include/modules.h
+++ b/src/include/modules.h
@@ -1,8 +1,25 @@
 /*
+ *   This program is free software; you can redistribute it and/or modify
+ *   it under the terms of the GNU General Public License as published by
+ *   the Free Software Foundation; either version 2 of the License, or
+ *   (at your option) any later version.
+ *
+ *   This program is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *   GNU General Public License for more details.
+ *
+ *   You should have received a copy of the GNU General Public License
+ *   along with this program; if not, write to the Free Software
+ *   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+ 
+/*
+ * $Id$
+ *
  * @file modules.h
  * @brief Interface to the RADIUS module system.
  *
- * @version $Id$
  * @copyright 2013 The FreeRADIUS server project
  */
 

diff --git a/src/include/radiusd.h b/src/include/radiusd.h
index 8aa9b869a16b35697f00ceb8706a7ee4c285ce1f..7e0081459e66255efb07275b519b9838383dbf97 100644 (file)
--- a/src/include/radiusd.h
+++ b/src/include/radiusd.h
@@ -16,11 +16,12 @@
 #ifndef RADIUSD_H
 #define RADIUSD_H
 /*
+ * $Id$
+ *
  * @file radiusd.h
  * @brief Structures, prototypes and global variables for the FreeRADIUS server.
  *
- * @version $Id$
- * @copyright 1999,2000,2002,2003,2004,2005,2006,2007,2008  The FreeRADIUS server project
+ * @copyright 1999-2000,2002-2008  The FreeRADIUS server project
  */
 
 #include <freeradius-devel/ident.h>

diff --git a/src/include/soh.h b/src/include/soh.h
index db3cc83efece1ed0d15ed34905d40a2f664a6926..96b750b90c60e0988e73d03a083f7f305c45f347 100644 (file)
--- a/src/include/soh.h
+++ b/src/include/soh.h
@@ -16,10 +16,11 @@
 #ifndef FR_SOH_H
 #define FR_SOH_H
 /*
+ * $Id$
+ *
  * @file soh.h
  * @brief Microsoft SoH support
  *
- * @version $Id$
  * @copyright 2010 Phil Mayers <p.mayers@imperial.ac.uk>
  */
 

diff --git a/src/include/tcp.h b/src/include/tcp.h
index cb86062ac4d8eca291454ac419cafdb3788c3805..c45779e8123bfa4e2ccdb5d6a1566d4d5471d0d9 100644 (file)
--- a/src/include/tcp.h
+++ b/src/include/tcp.h
@@ -16,10 +16,11 @@
 #ifndef FR_TCP_H
 #define FR_TCP_H
 /*
+ * $Id$
+ *
  * @file tcp.h
  * @brief RADIUS over TCP
  *
- * @version $Id$
  * @copyright 2009 Dante http://dante.net
  */
 

diff --git a/src/include/tls-h b/src/include/tls-h
index d855c6a5a9418044f84976b16ce16a1df22e5a02..a44c134af0e93da262189fbdba7b99d9a23c4297 100644 (file)
--- a/src/include/tls-h
+++ b/src/include/tls-h
@@ -18,10 +18,11 @@
 
 #ifdef WITH_TLS
 /*
+ * $Id$
+ *
  * @file tls.h
  * @brief Structures and prototypes for TLS wrappers
  *
- * @version $Id$
  * @copyright 2010 Network RADIUS SARL <info@networkradius.com>
  */
 

diff --git a/src/include/token.h b/src/include/token.h
index c3bf7753d30ba8c74d1c8b22e841051ead87ed1f..bdf60bf4a0e8434ba34cd65b76a1ad2937c3caf9 100644 (file)
--- a/src/include/token.h
+++ b/src/include/token.h
@@ -17,10 +17,11 @@
 #define FR_TOKEN_H
 
 /*
+ * $Id$
+ *
  * @file token.h
  * @brief Tokenisation code and constants.
  *
- * @version $Id$
  * @copyright 2001,2006  The FreeRADIUS server project
  */
 

diff --git a/src/include/udpfromto.h b/src/include/udpfromto.h
index 3e7ddb8395aa4c73ab5eb17d6c69db9ed78c9377..3a954ff8035ae849593e1b8cddde6cd3caa43a18 100644 (file)
--- a/src/include/udpfromto.h
+++ b/src/include/udpfromto.h
@@ -1,10 +1,9 @@
 #ifndef UDPFROMTO_H
 #define UDPFROMTO_H
 /*
- * @file udpfromto.h
+ * $Id$
  *
- * @version $Id$
- * @copyright 2013  The FreeRADIUS server project
+ * @file udpfromto.h
  */
 
 #include <freeradius-devel/ident.h>

diff --git a/src/include/vmps.h b/src/include/vmps.h
index fb7bd1b2c51f582dc49e5e4c3ae636827b19a5d5..69eb558afcd9510bae6f5ef21ac6fda7ddaf10f2 100644 (file)
--- a/src/include/vmps.h
+++ b/src/include/vmps.h
@@ -1,11 +1,27 @@
+/*
+ *   This program is free software; you can redistribute it and/or modify
+ *   it under the terms of the GNU General Public License as published by
+ *   the Free Software Foundation; either version 2 of the License, or
+ *   (at your option) any later version.
+ *
+ *   This program is distributed in the hope that it will be useful,
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *   GNU General Public License for more details.
+ *
+ *   You should have received a copy of the GNU General Public License
+ *   along with this program; if not, write to the Free Software
+ *   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+ */
 #ifndef VMPS_H
 #define VMPS_H
 /*
+ * $Id$
+ *
  * @file vmps.h
  * @brief Routines to handle VMPS sockets.
  *
- * @version $Id$
- * @copyright 2013  The FreeRADIUS server project
+ * @copyright 2013 The FreeRADIUS server project
  */
 
 #include <freeradius-devel/ident.h>

diff --git a/src/include/vqp.h b/src/include/vqp.h
index 6c598ecf60be5453594f7f06ea854235d1e7fc20..a875a649d9ae3a181f42e9a58e5ef13d36634474 100644 (file)
--- a/src/include/vqp.h
+++ b/src/include/vqp.h
@@ -17,10 +17,11 @@
 #define FR_VQP_H
 
 /*
+ * $Id$
+ *
  * @file vqp.h
  * @brief Structures and prototypes for Cisco's VLAN Query Protocol
  *
- * @version $Id$
  * @copyright 2007  The FreeRADIUS server project
  * @copyright 2007  Alan DeKok <aland@deployingradius.com>
  */

diff --git a/src/lib/radius.c b/src/lib/radius.c
index 30f3be041a344b52e88f1730067f8a50b5e612c8..e08420f423f89e32631d440ed68e8c0320a17bab 100644 (file)
--- a/src/lib/radius.c
+++ b/src/lib/radius.c
@@ -15,10 +15,11 @@
  */
 
 /*
+ * $Id$
+ *
  * @file radius.c
  * @brief Functions to send/receive radius packets.
  *
- * @version $Id$
  * @copyright 2000-2003,2006  The FreeRADIUS server project
  */
 

diff --git a/src/main/connection.c b/src/main/connection.c
index 56c7736b82b698637a0a657941ca10dcdad513ce..0ceaa39ea2c3856dfc3eda0c1e7e6d0c5b32aba4 100644 (file)
--- a/src/main/connection.c
+++ b/src/main/connection.c
@@ -82,7 +82,7 @@ struct fr_connection_pool_t {
                                        //!< and maintain.
        int             cleanup_delay;  //!< How long a connection can go unused
                                        //!< for before it's closed
-                                       //!< (0 is infinite)
+                                       //!< (0 is infinite).
        int             max_uses;       //!< Maximum number of times a
                                        //!< connection can be used before being
                                        //!< closed.
@@ -105,9 +105,10 @@ struct fr_connection_pool_t {
                                        //!< configuration parameters.
        time_t          last_throttled; //!< Last time we refused to spawn a 
                                        //!< connection because the last
-                                       //!< connection failed.
+                                       //!< connection failed, or we were 
+                                       //!< already spawning a connection.
        time_t          last_at_max;    //!< Last time we hit the maximum number
-                                       //!< of allowed connections
+                                       //!< of allowed connections.
                                        
        unsigned int    count;          //!< Number of connections spawned over
                                        //!< the lifetime of the pool.
@@ -430,7 +431,7 @@ static void fr_connection_close(fr_connection_pool_t *pool,
 /** Find a connection handle in the connection list
  *
  * Walks over the list of connections searching for a specified connection
- * handle, and returns the first connection that contains that pointer.
+ * handle and returns the first connection that contains that pointer.
  * 
  * @note Will lock mutex and only release mutex if connection handle
  * is not found, so will usually return will mutex held.

diff --git a/src/main/exec.c b/src/main/exec.c
index bbcb6f24b30c238190b6860b6c3a3d69f7a97eee..88865d8dd87bd037f2a0611a545ac276773edc8f 100644 (file)
--- a/src/main/exec.c
+++ b/src/main/exec.c
@@ -15,10 +15,11 @@
  */
  
 /*
+ * $Id$
+ *
  * @file exec.c
  * @brief Execute external programs.
  *
- * @version $Id$
  * @copyright 2000-2004,2006  The FreeRADIUS server project
  */
 

diff --git a/src/main/process.c b/src/main/process.c
index 49c5ec19fec6cef175600ffba1448955f55a1f29..518081fc32cc4af1dcf6e6a543fe6f2fadcea007 100644 (file)
--- a/src/main/process.c
+++ b/src/main/process.c
@@ -14,11 +14,12 @@
  *   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
  */
 
-/**
+/*
+ * $Id$
+ *
  * @file process.c
  * @brief Defines the state machines that control how requests are processed.
  *
- * @version $Id$
  * @copyright 2012  The FreeRADIUS server project
  * @copyright 2012  Alan DeKok <aland@deployingradius.com>
  */

diff --git a/src/main/soh.c b/src/main/soh.c
index 293f35c94616861712e1257b3952d65f1f005763..a17980acded3acdf8cf62cd2deb34f1800948868 100644 (file)
--- a/src/main/soh.c
+++ b/src/main/soh.c
@@ -15,10 +15,11 @@
  */
 
 /*
+ * $Id$
+ *
  * @file soh.c
  * @brief Implements the MS-SOH parsing code. This is called from rlm_eap_peap
  *
- * @version $Id$
  * @copyright 2010 Phil Mayers <p.mayers@imperial.ac.uk>
  */
 

diff --git a/src/main/valuepair.c b/src/main/valuepair.c
index 5607caf1b59d988edbe0c5a67b1b15f9ef65a790..98c4da60afe8fdef22fe6192f2bd52d773e4acfb 100644 (file)
--- a/src/main/valuepair.c
+++ b/src/main/valuepair.c
@@ -15,13 +15,14 @@
  */
 
 /*
+ * $Id$
+ *
  * @brief Valuepair functions that are radiusd-specific and as such do not
  *       belong in the library.
  * @file main/valuepair.c
  *
  * @ingroup AVP
  *
- * @version $Id$
  * @copyright 2000,2006  The FreeRADIUS server project
  * @copyright 2000  Alan DeKok <aland@ox.org>
  */

diff --git a/src/main/xlat.c b/src/main/xlat.c
index 8af4e1dd9b4fb6371455d7bc8d9b879d77bc6394..d7606c87b1de699fca63f9795d17104b5bff4379 100644 (file)
--- a/src/main/xlat.c
+++ b/src/main/xlat.c
@@ -15,10 +15,11 @@
  */
 
 /*
+ * $Id$
+ *
  * @file xlat.c
  * @brief String expansion ("translation"). Implements %Attribute -> value
  *
- * @version $Id$
  * @copyright 2000,2006  The FreeRADIUS server project
  * @copyright 2000  Alan DeKok <aland@ox.org>
  */

diff --git a/src/modules/rlm_rest/rest.c b/src/modules/rlm_rest/rest.c
index 1d6ac4bf3ed35480ab0321ef0d79932e63731302..1641f13a93106b2593c09e14b5267f2951f8510a 100644 (file)
--- a/src/modules/rlm_rest/rest.c
+++ b/src/modules/rlm_rest/rest.c
@@ -14,11 +14,12 @@
  *   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
  */
  
-/** 
+/*
+ * $Id$
+ *
  * @brief Functions and datatypes for the REST (HTTP) transport.
  * @file rest.c
  *
- * @version $Id$
  * @copyright 2012-2013  Arran Cudbard-Bell <a.cudbard-bell@freeradius.org>
  */
 

diff --git a/src/modules/rlm_rest/rest.h b/src/modules/rlm_rest/rest.h
index f74c11bb07695b67f8c1bc7478cd820722bce245..aa1df13698f353a1ed29d64adbf7691d8b7df01d 100644 (file)
--- a/src/modules/rlm_rest/rest.h
+++ b/src/modules/rlm_rest/rest.h
@@ -15,17 +15,18 @@
  */
  
 /*
- * @brief Function prototypes datatypes for the REST (HTTP) transport.
+ * $Id$
+ *
+ * @brief Function prototypes and datatypes for the REST (HTTP) transport.
  * @file rest.h
  *
- * @version $Id$
  * @copyright 2012-2013  Arran Cudbard-Bell <a.cudbard-bell@freeradius.org>
  */
+ 
 #include <freeradius-devel/ident.h>
-#include <freeradius-devel/connection.h>
-
 RCSIDH(other_h, "$Id$")
 
+#include <freeradius-devel/connection.h>
 #include "config.h"
 
 #ifdef HAVE_JSON_JSONH