start on doxygenization of guts

[disorder] / lib / addr.c

diff --git a/lib/addr.c b/lib/addr.c
index 16cd610686391c0cf7ec5f09e4e71a82d6c1b56b..153130bf65cf31634d8187ee4e3b917f0d63731e 100644 (file)
--- a/lib/addr.c
+++ b/lib/addr.c
@@ -33,6 +33,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) {