stop mumbling in dispatch.h by filling out the comments. Fixed a bug, since I was here already.

lib/dns/dispatch.c

@@ -15,7 +15,7 @@
  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/* $Id: dispatch.c,v 1.64 2000/08/26 01:36:49 bwelling Exp $ */
+/* $Id: dispatch.c,v 1.65 2000/09/01 07:16:04 explorer Exp $ */
 
 #include <config.h>
 
@@ -2148,6 +2148,12 @@ void
 dns_dispatch_changeattributes(dns_dispatch_t *disp,
 			      unsigned int attributes, unsigned int mask)
 {
+	REQUIRE(VALID_DISPATCH(disp));
+
+	/* XXXMLG
+	 * Should check for valid attributes here!
+	 */
+
 	LOCK(&disp->lock);
 	disp->attributes &= ~mask;
 	disp->attributes |= (attributes & mask);

lib/dns/include/dns/dispatch.h

@@ -15,7 +15,7 @@
  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
-/* $Id: dispatch.h,v 1.35 2000/08/01 01:24:08 tale Exp $ */
+/* $Id: dispatch.h,v 1.36 2000/09/01 07:16:06 explorer Exp $ */
 
 #ifndef DNS_DISPATCH_H
 #define DNS_DISPATCH_H 1
@@ -192,16 +192,27 @@ dns_dispatch_getudp(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr,
 		    dns_dispatch_t **dispp);
 /*
  * Attach to existing dns_dispatch_t if one is found with dns_dispatchmgr_find,
- *	otherwise create a new UDP dispatch.
+ * otherwise create a new UDP dispatch.
  *
  * Requires:
- *	< mumble >
+ *	All pointer parameters be valid for their respective types.
  *
- * Ensures:
- *	< mumble >
+ *	dispp != NULL && *disp == NULL
+ *
+ *	512 <= buffersize <= 64k
+ *
+ *	maxbuffers > 0
+ *
+ *	buckets < 2097169
+ *
+ *	increment > buckets
+ *
+ *	(attributes & DNS_DISPATCHATTR_TCP) == 0
  *
  * Returns:
- *	< mumble >
+ *	ISC_R_SUCCESS	-- success.
+ *
+ *	Anything else	-- failure.
  */
 
 isc_result_t
@@ -233,8 +244,7 @@ dns_dispatch_createtcp(dns_dispatchmgr_t *mgr, isc_socket_t *sock,
  *
  *	task is a valid task that can be used internally to this dispatcher.
  *
- * 	"buffersize" >= 512, which is the minimum receive size for a
- *	DNS message.
+ * 	512 <= buffersize <= 64k
  *
  *	maxbuffers > 0.
  *
@@ -246,6 +256,11 @@ dns_dispatch_createtcp(dns_dispatchmgr_t *mgr, isc_socket_t *sock,
  *
  *	attributes includes DNS_DISPATCHATTR_TCP and does not include
  *	DNS_DISPATCHATTR_UDP.
+ *
+ * Returns:
+ *	ISC_R_SUCCESS	-- success.
+ *
+ *	Anything else	-- failure.
  */
 
 void
@@ -254,13 +269,9 @@ dns_dispatch_attach(dns_dispatch_t *disp, dns_dispatch_t **dispp);
  * Attach to a dispatch handle.
  *
  * Requires:
- *	< mumble >
+ *	disp is valid.
  *
- * Ensures:
- *	< mumble >
- *
- * Returns:
- *	< mumble >
+ *	dispp != NULL && *dispp == NULL
  */
 
 void
@@ -269,13 +280,7 @@ dns_dispatch_detach(dns_dispatch_t **dispp);
  * Detaches from the dispatch.
  *
  * Requires:
- *	< mumble >
- *
- * Ensures:
- *	< mumble >
- *
- * Returns:
- *	< mumble >
+ *	dispp != NULL and *dispp be a valid dispatch.
  */
 
 void
@@ -335,12 +340,6 @@ dns_dispatch_removeresponse(dns_dispentry_t **resp,
  * Requires:
  *	"resp" != NULL and "*resp" contain a value previously allocated
  *	by dns_dispatch_addresponse();
- *
- * Ensures:
- *	< mumble >
- *
- * Returns:
- *	< mumble >
  */
 
 
@@ -354,13 +353,16 @@ dns_dispatch_addrequest(dns_dispatch_t *disp,
  * or through dns_dispatch_removerequest() for another to be delivered.
  *
  * Requires:
- *	< mumble >
+ *	disp is valid.
  *
- * Ensures:
- *	< mumble >
+ *	task, action, and arg is valid.
+ *
+ *	resp != NULL && *resp == NULL
  *
  * Returns:
- *	< mumble >
+ *	ISC_R_SUCCESS	-- success.
+ *
+ *	Anything else	-- failure.
  */
 
 
@@ -373,13 +375,9 @@ dns_dispatch_removerequest(dns_dispentry_t **resp,
  * also returned to the system.
  *
  * Requires:
- *	< mumble >
+ *	resp != NULL and *resp is valid.
  *
- * Ensures:
- *	< mumble >
- *
- * Returns:
- *	< mumble >
+ *	If sockevent != NULL, *sockevent must is valid.
  */
 
 
@@ -392,13 +390,12 @@ dns_dispatch_freeevent(dns_dispatch_t *disp, dns_dispentry_t *resp,
  * processed, and the associated buffer is no longer needed.
  *
  * Requires:
- *	< mumble >
+ *	disp is valid.
  *
- * Ensures:
- *	< mumble >
+ *	resp is valid.
  *
- * Returns:
- *	< mumble >
+ *	sockevent != NULL && *sockevent is valid.
+ *	
  */
 
 
@@ -408,13 +405,10 @@ dns_dispatch_getsocket(dns_dispatch_t *disp);
  * Return the socket associated with this dispatcher.
  *
  * Requires:
- *	< mumble >
- *
- * Ensures:
- *	< mumble >
+ *	disp is valid.
  *
  * Returns:
- *	< mumble >
+ *	The socket the dispatcher is using.
  */
 
 
@@ -424,13 +418,7 @@ dns_dispatch_cancel(dns_dispatch_t *disp);
  * cancel outstanding clients
  *
  * Requires:
- *	< mumble >
- *
- * Ensures:
- *	< mumble >
- *
- * Returns:
- *	< mumble >
+ *	disp is valid.
  */
 
 void
@@ -440,14 +428,15 @@ dns_dispatch_changeattributes(dns_dispatch_t *disp,
  * Set the bits described by "mask" to the corresponding values in
  * "attributes".
  *
+ * That is:
+ *
+ *	new = (old & ~mask) | (attributes & mask)
+ *
  * Requires:
- *	< mumble >
+ *	disp is valid.
  *
- * Ensures:
- *	< mumble >
- *
- * Returns:
- *	< mumble >
+ *	attributes are reasonable for the dispatch.  That is, setting the UDP
+ *	attribute on a TCP socket isn't reasonable.
  */
 
 ISC_LANG_ENDDECLS