Fix issues found by nickm.

* Document fmt_addr_impl() and friends.
* Parenthesize macro arguments.
* Rename get_first_listener_addrport_for_pt() to
  get_first_listener_addrport_string().
* Handle port_cfg_t with no_listen.
* Handle failure of router_get_active_listener_port_by_type().
* Add an XXX to router_get_active_listener_port_by_type().

2 files changed, 16 insertions, 6 deletions

diff --git a/src/common/address.c b/src/common/address.c
index 62cf16c03c..7f78d1e4d3 100644
--- a/src/common/address.c
+++ b/src/common/address.c
@@ -986,10 +986,15 @@ tor_dup_addr(const tor_addr_t *addr)
   }
 }
 
-/** Return a string representing the address <b>addr</b>.  This string is
- * statically allocated, and must not be freed.  Each call to
- * <b>fmt_addr</b> invalidates the last result of the function.  This
- * function is not thread-safe. */
+/** Return a string representing the address <b>addr</b>.  This string
+ * is statically allocated, and must not be freed.  Each call to
+ * <b>fmt_addr_impl</b> invalidates the last result of the function.
+ * This function is not thread-safe. If <b>decorate</b> is set, add
+ * brackets to IPv6 addresses.
+ *
+ * It's better to use the wrapper macros of this function:
+ * <b>fmt_addr()</b> and <b>fmt_and_decorate_addr()</b>.
+ */
 const char *
 fmt_addr_impl(const tor_addr_t *addr, int decorate)
 {
diff --git a/src/common/address.h b/src/common/address.h
index bdb14eb390..761eed661c 100644
--- a/src/common/address.h
+++ b/src/common/address.h
@@ -135,8 +135,13 @@ tor_addr_eq_ipv4h(const tor_addr_t *a, uint32_t u)
 
 int tor_addr_lookup(const char *name, uint16_t family, tor_addr_t *addr_out);
 char *tor_dup_addr(const tor_addr_t *addr) ATTR_MALLOC;
-#define fmt_addr(a) fmt_addr_impl(a, 0)
-#define fmt_and_decorate_addr(a) fmt_addr_impl(a, 1)
+
+/** Wrapper function of fmt_addr_impl(). It does not decorate IPv6
+ *  addresses. */
+#define fmt_addr(a) fmt_addr_impl((a), 0)
+/** Wrapper function of fmt_addr_impl(). It decorates IPv6
+ *  addresses. */
+#define fmt_and_decorate_addr(a) fmt_addr_impl((a), 1)
 const char *fmt_addr_impl(const tor_addr_t *addr, int decorate);
 const char * fmt_addr32(uint32_t addr);
 int get_interface_address6(int severity, sa_family_t family, tor_addr_t *addr);