diff --git a/lib/lwres/include/lwres/context.h b/lib/lwres/include/lwres/context.h
index 2253d19cd5..78f44cda3e 100644
--- a/lib/lwres/include/lwres/context.h
+++ b/lib/lwres/include/lwres/context.h
@@ -34,6 +34,21 @@ LWRES_LANG_BEGINDECLS
 typedef void *(*lwres_malloc_t)(void *arg, size_t length);
 typedef void (*lwres_free_t)(void *arg, void *mem, size_t length);
 
+/*
+ * XXXMLG
+ *
+ * Make the server reload /etc/resolv.conf periodlically.
+ *
+ * Make the server do sortlist/searchlist.
+ *
+ * Client side can disable the search/sortlist processing.
+ *
+ * Use an array of addresses/masks and searchlist for client-side, and
+ * if added to the client disable the processing on the server.
+ *
+ * Share /etc/resolv.conf data between contexts.
+ */
+
 lwres_result_t
 lwres_context_create(lwres_context_t **contextp, void *arg,
 		     lwres_malloc_t malloc_function,
@@ -45,6 +60,9 @@ lwres_context_create(lwres_context_t **contextp, void *arg,
  * If one is non-NULL, they must both be non-NULL.  "arg" is passed to
  * these functions.
  *
+ * Contexts are not thread safe.  Document at the top of the file.
+ * XXXMLG
+ *
  * If they are NULL, the standard malloc() and free() will be used.
  *
  * Requires:
@@ -68,6 +86,9 @@ lwres_context_destroy(lwres_context_t **contextp);
 
 lwres_uint32_t
 lwres_context_nextserial(lwres_context_t *ctx);
+/*
+ * XXXMLG Document
+ */
 
 void
 lwres_context_initserial(lwres_context_t *ctx, lwres_uint32_t serial);
diff --git a/lib/lwres/include/lwres/lwpacket.h b/lib/lwres/include/lwres/lwpacket.h
index 2e614432e5..fe70e6f7cc 100644
--- a/lib/lwres/include/lwres/lwpacket.h
+++ b/lib/lwres/include/lwres/lwpacket.h
@@ -79,10 +79,12 @@ struct lwres_lwpacket {
  *
  * "authtype" is the packet level auth type used.
  * Authtypes between 0x1000 and 0xffff are application defined.  Authtypes
- * between 0x0000 and 0x0fff are reserved for library use.
+ * between 0x0000 and 0x0fff are reserved for library use.  This is currently
+ * unused and MUST be set to zero.
  *
  * "authlen" is the length of the authentication data.  See the specific
- * authtypes for more information on what is contained in this field.
+ * authtypes for more information on what is contained in this field.  This
+ * is currently unused, and MUST be set to zero.
  *
  * The remainder of the packet consists of two regions, one described by
  * "authlen" and one of "length - authlen - sizeof(lwres_lwpacket_t)".
@@ -94,9 +96,8 @@ struct lwres_lwpacket {
  *	data bytes
  */
 
-/* XXXMLG Some of this belongs here, some elsewhere.
- *
- * Initially, we will define only a few opcodes:
+/*
+ * Currently defined opcodes:
  *
  *	NOOP.  Success is always returned, with the packet contents echoed.
  *
@@ -107,14 +108,11 @@ struct lwres_lwpacket {
  *
  *	GETNAMEBYADDR.	Return the hostname for the given address.  Once
  *		again, it will return data from multiple sources.
- *
- *	GETDNSTYPE.  Return information about a given name using DNS
- *		specific structure formats.  That is, one can request MX,
- *		NS, SOA, etc. using this opcode.
  */
 
 LWRES_LANG_BEGINDECLS
 
+/* XXXMLG document */
 lwres_result_t
 lwres_lwpacket_renderheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt);
 
diff --git a/lib/lwres/include/lwres/lwres.h b/lib/lwres/include/lwres/lwres.h
index 4cc378b685..39a919c115 100644
--- a/lib/lwres/include/lwres/lwres.h
+++ b/lib/lwres/include/lwres/lwres.h
@@ -78,17 +78,9 @@
  *	response_free().
  */
 
-/*
- * Helper macro to calculate a string's length.  Strings are encoded
- * using a 16-bit length, the string itself, and a trailing NUL.  The
- * length does not include this NUL character -- it is there merely to
- * help reduce copying on the receive side, since most strings are
- * printable character strings, and C needs the trailing NUL.
- */
-
 #define LWRES_UDP_PORT		921	/* XXXMLG */
-#define LWRES_RECVLENGTH	2048	/* XXXMLG */
-#define LWRES_ADDR_MAXLEN	16	/* XXXMLG changing this breaks ABI */
+#define LWRES_RECVLENGTH	4096	/* XXXMLG */
+#define LWRES_ADDR_MAXLEN	16	/* changing this breaks ABI */
 
 /*
  * XXXMLG
@@ -98,7 +90,7 @@
 #endif
 
 /*
- * NO-OP
+ * no-op
  */
 #define LWRES_OPCODE_NOOP		0x00000000U
 
@@ -115,7 +107,7 @@ typedef struct {
 } lwres_noopresponse_t;
 
 /*
- * GET ADDRESSES BY NAME
+ * get addresses by name
  */
 #define LWRES_OPCODE_GETADDRSBYNAME	0x00010001U
 
@@ -151,7 +143,7 @@ typedef struct {
 } lwres_gabnresponse_t;
 
 /*
- * GET NAME BY ADDRESS
+ * get name by address
  */
 #define LWRES_OPCODE_GETNAMEBYADDR	0x00010002U
 typedef struct {
@@ -171,9 +163,8 @@ typedef struct {
 	size_t				baselen;
 } lwres_gnbaresponse_t;
 
-
 /*
- * resolv.conf DATA
+ * resolv.conf data
  */
 
 #define LWRES_CONFMAXNAMESERVERS 3	/* max 3 "nameserver" entries */