X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/e83d0967d4c0965eb8036248acc20d1bf12ad1d8..ad58ebcc8a950f4624cfb1a836e18a703c3b6610:/lib/addr.c

diff --git a/lib/addr.c b/lib/addr.c
index 16cd610..579fd0f 100644
--- a/lib/addr.c
+++ b/lib/addr.c
@@ -17,6 +17,7 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  * USA
  */
+/** @file lib/addr.c Socket address support */
 
 #include <config.h>
 #include "types.h"
@@ -33,6 +34,24 @@
 #include "configuration.h"
 #include "addr.h"
 
+/** @brief Convert a pair of strings to an address
+ * @param a Pointer to string list
+ * @param pref Hints structure for getaddrinfo, or NULL
+ * @param namep Where to store address description, or NULL
+ * @return Address info structure or NULL on error
+ *
+ * This converts one or two strings into an address specification suitable
+ * for passing to socket(), bind() etc.
+ *
+ * If there is only one string then it is assumed to be the service
+ * name (port number).  If there are two then the first is the host
+ * name and the second the service name.
+ *
+ * @p namep is used to return a description of the address suitable
+ * for use in log messages.
+ *
+ * If an error occurs a message is logged and a null pointer returned.
+ */
 struct addrinfo *get_address(const struct stringlist *a,
 			     const struct addrinfo *pref,
 			     char **namep) {
@@ -70,6 +89,10 @@ struct addrinfo *get_address(const struct stringlist *a,
   return res;
 }
 
+/** @brief Comparison function for address information
+ *
+ * Suitable for qsort().
+ */
 int addrinfocmp(const struct addrinfo *a,
 		const struct addrinfo *b) {
   const struct sockaddr_in *ina, *inb;