- * if you are reading this code for the first time, start at the
- * bottom and work your way upwards
+ * If you are reading this code for the first time, read the rest of
+ * this comment block, then start at the bottom of the file and work
+ * your way upwards.
+ *
+ * All functions which return an int use zero to signal success --
+ * except cpstr(), which returns zero on *failure*. This should be
+ * fixed.
+ *
+ * A note about memory allocation:
+ *
+ * NSS plugins generally ought to work without attempting to call
+ * malloc() (which may fail). Therefore, glibc allocates a buffer
+ * before calling NSS library functions, and passes that buffer to
+ * the NSS library; library functions store their results in the
+ * buffer and return pointers into that buffer.
+ *
+ * The convention used throughout this library is to pass around a
+ * char** which points to a pointer to the first unused byte in the
+ * provided buffer, and a size_t* which points to an int indicating
+ * how many bytes are left between the char** and the end of the
+ * available region.