[V2] Enhance comments in nsswitch.h

diff --git a/ChangeLog b/ChangeLog
index cfdfcd57b7..0e3e2dd779 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@ 
+2019-05-14  DJ Delorie  <dj@redhat.com>
+
+	* nss/nsswitch.h: Add more comments.
+
 2019-05-14  Florian Weimer  <fweimer@redhat.com>
 
 	Linux: Add the tgkill function.
diff --git a/nss/nsswitch.h b/nss/nsswitch.h
index 475e007e33..756db903b2 100644
--- a/nss/nsswitch.h
+++ b/nss/nsswitch.h
@@ -36,6 +36,19 @@  typedef enum
   NSS_ACTION_MERGE
 } lookup_actions;
 
+/* The NSS implementation uses a variety of data structures to
+   implement the service plugin management.  Some of this data
+   once loaded must be persistent.  Some of this data once loaded
+   could subsequently be unloaded.  These comments are here to help
+   guide a future implementation where we might unload this data.
+
+   We define several types of pointers to try help identify the data:
+   - ptr-to-malloc'd: Pointer to data which needs freeing.
+   - ptr-to-persistent: Pointer to persistent object.
+   - ptr-to-unloadable: Pointer to unloadlable object.  */
+
+/* The following structures generally hold persistent data
+   that cannot (or at least need not) be unloaded:  */
 
 typedef struct service_library
 {
@@ -43,7 +56,9 @@  typedef struct service_library
   const char *name;
   /* Pointer to the loaded shared library.  */
   void *lib_handle;
-  /* And the link to the next entry.  */
+  /* The link to the next entry, set by nss_new_service.  This link is
+     used to free resources, and is not related to the order of
+     handlers for each service (that is NEXT in service_user).  */
   struct service_library *next;
 } service_library;
 
@@ -53,20 +68,28 @@  typedef struct service_library
    is the first member.  */
 typedef struct
 {
-  const char *fct_name;
-  void *fct_ptr;
+  /* This is the API name, like `gethostbyname_r'.  */
+  const char *fct_name; /* ptr-to-malloc'd */
+  /* This is the DSO function, like _nss_dns_gethostbyname_r().  */
+  void *fct_ptr; /* ptr-to-persistent */
 } known_function;
 
+/* The following structures generally hold data that may be unloaded
+   at runtime and/or replaced, such as if nsswitch.conf is
+   reloaded: */
 
 typedef struct service_user
 {
-  /* And the link to the next entry.  */
-  struct service_user *next;
+  /* The link to the next entry.  In a line like `a : b c d' this is
+     the b->c->d link.  */
+  struct service_user *next; /* ptr-to-unloadable */
   /* Action according to result.  */
   lookup_actions actions[5];
   /* Link to the underlying library object.  */
-  service_library *library;
-  /* Collection of known functions.  */
+  service_library *library; /* ptr-to-persistent */
+  /* Collection of known functions, mapping (for example) `foo' to
+     _nss_dns_foo().  Only contains mappings for this service and this
+     DSO, so at least one and at most a few mappings.  */
   void *known;
   /* Name of the service (`files', `dns', `nis', ...).  */
   char name[0];
@@ -78,11 +101,13 @@  typedef struct service_user
 
 typedef struct name_database_entry
 {
-  /* And the link to the next entry.  */
-  struct name_database_entry *next;
-  /* List of service to be used.  */
-  service_user *service;
-  /* Name of the database.  */
+  /* The link to the next entry.  In a typical nsswitch.conf, this is
+     the passwd->group->hosts link, i.e. the next non-comment line in
+     the file.  */
+  struct name_database_entry *next; /* ptr-to-unloadable */
+  /* List of services to be used.  */
+  service_user *service; /* ptr-to-unloadable */
+  /* Name of the database (`passwd', `hosts', etc).  */
   char name[0];
 } name_database_entry;
 
@@ -90,9 +115,9 @@  typedef struct name_database_entry
 typedef struct name_database
 {
   /* List of all known databases.  */
-  name_database_entry *entry;
+  name_database_entry *entry; /* ptr-to-unloadable */
   /* List of libraries with service implementation.  */
-  service_library *library;
+  service_library *library; /* ptr-to-persistent */
 } name_database;