update comments

lib/dns/include/dns/adb.h

@@ -26,9 +26,9 @@
 /*
  * DNS Address Database
  *
- * This module implements an address database (ADB) for mapping an
+ * This module implements an address database (ADB) for mapping a name
- * NS rdata record to an isc_sockaddr_t. It also provides statistical
+ * to an isc_sockaddr_t. It also provides statistical information on
- * information on how good that address might be.
+ * how good that address might be.
  *
  * A client will pass in a dns_name_t, and the ADB will walk through
  * the rdataset looking up addresses associated with the name.  If it
@@ -36,7 +36,7 @@
  * address information and stats for found addresses.
  *
  * If the name cannot be found on the internal lists, a new entry will
- * be created for an name if all the information needed can be found
+ * be created for a name if all the information needed can be found
  * in the zone table or cache.  This new address will then be returned.
  *
  * If a request must be made to remote servers to satisfy a name lookup,
@@ -70,7 +70,7 @@
  */
 
 /***
- *** IMPORTS
+ *** Imports
  ***/
 
 #include <stdio.h>
@@ -109,9 +109,7 @@ typedef struct dns_adbname		dns_adbname_t;
 
 /* dns_adbfind_t
  *
- * The find into our internal state of what is going on, where, when...
+ * Represents a lookup for a single name.
- * This is returned to the user as a find, so requests can be canceled,
- * etc.
  *
  * On return, the client can safely use "list", and can reorder the list.
  * Items may not be _deleted_ from this list, however, or added to it
@@ -143,7 +141,7 @@ struct dns_adbfind {
 #define DNS_ADBFIND_EMPTYEVENT		0x00000004
 #define DNS_ADBFIND_WANTEVENT		0x00000008
 
-/* dns_adbaddr_t
+/* dns_adbaddrinfo_t
  *
  * The answers to queries come back as a list of these.
  */
@@ -192,25 +190,29 @@ dns_adb_create(isc_mem_t *mem, dns_view_t *view, isc_timermgr_t *tmgr,
 /*
  * Create a new ADB.
  *
+ * Notes:
+ *
+ *	Generally, applications should not create an ADB directly, but
+ *	should instead call dns_view_createresolver().
+ *
  * Requires:
  *
- *	'mem' must be a pointer to a valid memory manager that all internal
+ *	'mem' must be a valid memory context.
- *	allocations will happen through (and so must remain valid at least
- *	until the new isc_addrtable_t is deleted)
  *
  *	'view' be a pointer to a valid view.
  *
  *	'tmgr' be a pointer to a valid timer manager.
  *
+ *	'taskmgr' be a pointer to a valid task manager.
+ *
  *	'newadb' != NULL && '*newadb' == NULL.
  *
  * Returns:
  *
- *	ISC_R_SUCCESS	after happiness
+ *	ISC_R_SUCCESS	after happiness.
  *	ISC_R_NOMEMORY	after resource allocation failure.
  */
 
-
 void
 dns_adb_detach(dns_adb_t **adb);
 /*
@@ -254,7 +256,7 @@ dns_adb_shutdown(dns_adb_t *adb);
 isc_result_t
 dns_adb_createfind(dns_adb_t *adb, isc_task_t *task, isc_taskaction_t action,
 		   void *arg, dns_name_t *name, dns_name_t *zone,
-		   unsigned int families, isc_stdtime_t now,
+		   unsigned int options, isc_stdtime_t now,
 		   dns_adbfind_t **find);
 /*
  * Main interface for clients. The adb will look up the name given in
@@ -279,6 +281,9 @@ dns_adb_createfind(dns_adb_t *adb, isc_task_t *task, isc_taskaction_t action,
  * the running database.  If specified as zero, the current time will
  * be retrieved and used.
  *
+ * XXXMLG  Document options, especially the flags which control how
+ *         events are sent.
+ *
  * Requires:
  *
  *	*adb be a valid isc_adb_t object.
@@ -330,9 +335,8 @@ dns_adb_deletename(dns_adb_t *adb, dns_name_t *host);
  *	ISC_R_NOTFOUND	-- the host is not in the database
  */
 
-
 isc_result_t
-dns_adb_insert(dns_adb_t *adb, dns_name_t *host, isc_sockaddr_t *addr,
+_dns_adb_insert(dns_adb_t *adb, dns_name_t *host, isc_sockaddr_t *addr,
 	       dns_ttl_t ttl, isc_stdtime_t now);
 /*
  * Insert a host name and address into the database.  A new (blank, no
@@ -364,6 +368,14 @@ dns_adb_cancelfind(dns_adbfind_t *find);
  * It is an error to call dns_adb_cancelfind() on a find where
  * no event is wanted, or will ever be sent.
  *
+ * Note:
+ *
+ *	It is possible that the real completion event was posted just
+ *	before the dns_adb_cancelfind() call was made.  In this case,
+ *	dns_adb_cancelfind() will do nothing.  The event callback needs
+ *	to be prepared to find this situation (i.e. result is valid but
+ *	the caller expects it to be canceled).
+ *
  * Requires:
  *
  *	'find' be a valid dns_adbfind_t pointer.
@@ -374,13 +386,6 @@ dns_adb_cancelfind(dns_adbfind_t *find);
  * Ensures:
  *
  *	The event was posted to the task.
- *
- * Note:
- *
- *	It is possible that the real completion event was posted just
- *	before the dns_adb_cancelfind() call was made.  In this case,
- *	dns_adb_cancelfind() will do nothing.  The event findr needs
- *	to be prepared to find this situation.
  */
 
 void
@@ -388,6 +393,12 @@ dns_adb_destroyfind(dns_adbfind_t **find);
 /*
  * Destroys the find reference.
  *
+ * Note:
+ *
+ *	This can only be called after the event was delivered for a
+ *	find.  Additionally, the event MUST have been freed via
+ *	isc_event_free() BEFORE this function is called.
+ *
  * Requires:
  *
  *	'find' != NULL and *find be valid dns_adbfind_t pointer.
@@ -396,39 +407,32 @@ dns_adb_destroyfind(dns_adbfind_t **find);
  *
  *	No "address found" events will be posted to the originating task
  *	after this function returns.
- *
- * Note:
- *
- *	This can only be called after the event was delivered for a
- *	find.  Additionally, the event MUST have been freed via
- *	isc_event_free() BEFORE this function is called.
  */
 
 void
 dns_adb_dump(dns_adb_t *adb, FILE *f);
 /*
- * This function is used only for debugging.  It will dump as much of the
+ * This function is only used for debugging.  It will dump as much of the
  * state of the running system as possible.
  *
  * Requires:
  *
  *	adb be valid.
  *
- *	f != NULL, and be a file open for writing.
+ *	f != NULL, and is a file open for writing.
  */
 
 void
 dns_adb_dumpfind(dns_adbfind_t *find, FILE *f);
 /*
- * Dump the data associated with a find.
+ * This function is only used for debugging.  Dump the data associated
+ * with a find.
  *
  * Requires:
  *
- *	adb be valid.
+ *	find is valid.
  *
- *	adbfind be valid.
+ * 	f != NULL, and is a file open for writing.
- *
- *	f != NULL, and be a file open for writing.
  */
 
 isc_result_t
@@ -459,18 +463,18 @@ dns_adb_adjustgoodness(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
 /*
  * Increase or decrease the address's goodness value.
  *
- * Requires:
- *
- *	adb be valid.
- *
- *	addr be valid.
- *
  * Note:
  *
  *	Goodness values are silently clamped to INT_MAX and INT_MIN.
  *
  *	The goodness in addr will be updated to reflect the new global
  *	goodness value.  This may include changes made by others.
+ *
+ * Requires:
+ *
+ *	adb be valid.
+ *
+ *	addr be valid.
  */
 
 /*
@@ -489,6 +493,10 @@ dns_adb_adjustsrtt(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
  *
  *	new_srtt = (old_srtt / 10 * factor) + (rtt / 10 * (10 - factor));
  *
+ * XXXRTH  Do we want to publish the formula?  What if we want to change how
+ *         this works later on?  Recommend/require that the units are
+ *	   microseconds?
+ *
  * Requires:
  *
  *	adb be valid.
@@ -518,13 +526,6 @@ dns_adb_changeflags(dns_adb_t *adb, dns_adbaddrinfo_t *addr,
  *	addr be valid.
  */
 
-/*
- * XXX Need functions/macros to:
- *
- *	Remove an address from a find's linked list.  This is needed
- *	because the data pointed to by a dns_adbaddr_t is reference counted.
- */
-
 ISC_LANG_ENDDECLS
 
 #endif /* DNS_ADB_H */