-improvements to docs

doc/examples/sessions.c

@@ -522,6 +522,7 @@ post_iterator (void *cls,
  *
  * @param cls argument given together with the function
  *        pointer when the handler was registered with MHD
+ * @param connection handle to connection which is being processed
  * @param url the requested url
  * @param method the HTTP method used ("GET", "PUT", etc.)
  * @param version the HTTP version string (i.e. "HTTP/1.1")
@@ -535,7 +536,7 @@ post_iterator (void *cls,
  * @param upload_data_size set initially to the size of the
  *        upload_data provided; the method must update this
  *        value to the number of bytes NOT processed;
- * @param con_cls pointer that the callback can set to some
+ * @param ptr pointer that the callback can set to some
  *        address and that will be preserved by MHD for future
  *        calls for this request; since the access handler may
  *        be called many times (i.e., for a PUT/POST operation

src/daemon/basicauth.c

@@ -100,10 +100,14 @@ MHD_basic_auth_get_username_password(struct MHD_Connection *connection,
 
 
 /**
- * Queues a response to request basic authentication from the client
+ * Queues a response to request basic authentication from the client.
+ * The given response object is expected to include the payload for
+ * the response; the "WWW-Authenticate" header will be added and the
+ * response queued with the 'UNAUTHORIZED' status code.
  *
  * @param connection The MHD connection structure
  * @param realm the realm presented to the client
+ * @param response response object to modify and queue
  * @return MHD_YES on success, MHD_NO otherwise
  */
 int 

src/daemon/connection.c

@@ -1107,7 +1107,7 @@ get_next_header_line (struct MHD_Connection *connection)
 	}        
       return NULL;
     }
-  /* found, check if we have proper CRLF */
+  /* found, check if we have proper LFCR */
   if (('\r' == rbuf[pos]) && ('\n' == rbuf[pos + 1]))
     rbuf[pos++] = '\0';         /* skip both r and n */
   rbuf[pos++] = '\0';

src/daemon/daemon.c

@@ -95,7 +95,7 @@
  * @param cls unused
  * @param file name of the file with the problem
  * @param line line number with the problem
- * @param msg error message with details
+ * @param reason error message with details
  */
 static void 
 mhd_panic_std (void *cls,
@@ -722,7 +722,7 @@ exit:
 /**
  * Callback for receiving data from the socket.
  *
- * @param conn the MHD connection structure
+ * @param connection the MHD connection structure
  * @param other where to write received data to
  * @param i maximum size of other (in bytes)
  * @return number of bytes actually received
@@ -747,7 +747,7 @@ recv_param_adapter (struct MHD_Connection *connection,
 /**
  * Callback for writing data to the socket.
  *
- * @param conn the MHD connection structure
+ * @param connection the MHD connection structure
  * @param other data to write
  * @param i number of bytes to write
  * @return actual number of bytes written
@@ -803,6 +803,9 @@ send_param_adapter (struct MHD_Connection *connection,
 
 /**
  * Signature of main function for a thread.
+ *
+ * @param cls closure argument for the function
+ * @return termination code from the thread
  */
 typedef void *(*ThreadStartRoutine)(void *cls);
 
@@ -817,7 +820,7 @@ typedef void *(*ThreadStartRoutine)(void *cls);
  * @return 0 on success
  */
 static int
-create_thread (pthread_t * thread,
+create_thread (pthread_t *thread,
 	       const struct MHD_Daemon *daemon,
 	       ThreadStartRoutine start_routine,
 	       void *arg)
@@ -1057,29 +1060,22 @@ MHD_add_connection (struct MHD_Daemon *daemon,
       gnutls_transport_set_ptr (connection->tls_session,
 				(gnutls_transport_ptr_t) connection);
       gnutls_transport_set_pull_function (connection->tls_session,
-					  (gnutls_pull_func) &
-                                               recv_param_adapter);
+					  (gnutls_pull_func) &recv_param_adapter);
       gnutls_transport_set_push_function (connection->tls_session,
-					  (gnutls_push_func) &
-                                               send_param_adapter);
+					  (gnutls_push_func) &send_param_adapter);
 
-      if (daemon->https_mem_trust){
-      gnutls_certificate_server_set_request(connection->tls_session, GNUTLS_CERT_REQUEST);
-      }
+      if (daemon->https_mem_trust)
+	  gnutls_certificate_server_set_request(connection->tls_session, GNUTLS_CERT_REQUEST);
     }
 #endif
 
   if (0 != pthread_mutex_lock(&daemon->cleanup_connection_mutex))
-    {
-      MHD_PANIC ("Failed to acquire cleanup mutex\n");
-    }
+    MHD_PANIC ("Failed to acquire cleanup mutex\n");    
   DLL_insert (daemon->connections_head,
 	      daemon->connections_tail,
 	      connection);
   if (0 != pthread_mutex_unlock(&daemon->cleanup_connection_mutex))
-    {
-      MHD_PANIC ("Failed to release cleanup mutex\n");
-    }
+    MHD_PANIC ("Failed to release cleanup mutex\n");    
 
   /* attempt to create handler thread */
   if (0 != (daemon->options & MHD_USE_THREAD_PER_CONNECTION))
@@ -1742,6 +1738,7 @@ MHD_select_thread (void *cls)
 /**
  * Start a webserver on the given port.
  *
+ * @param flags combination of MHD_FLAG values
  * @param port port to bind to
  * @param apc callback to call to check which clients
  *        will be allowed to connect
@@ -1751,7 +1748,7 @@ MHD_select_thread (void *cls)
  * @return NULL on error, handle to daemon on success
  */
 struct MHD_Daemon *
-MHD_start_daemon (unsigned int options,
+MHD_start_daemon (unsigned int flags,
                   uint16_t port,
                   MHD_AcceptPolicyCallback apc,
                   void *apc_cls,
@@ -1761,7 +1758,7 @@ MHD_start_daemon (unsigned int options,
   va_list ap;
 
   va_start (ap, dh_cls);
-  daemon = MHD_start_daemon_va (options, port, apc, apc_cls, dh, dh_cls, ap);
+  daemon = MHD_start_daemon_va (flags, port, apc, apc_cls, dh, dh_cls, ap);
   va_end (ap);
   return daemon;
 }
@@ -2163,16 +2160,19 @@ create_socket (int domain, int type, int protocol)
 /**
  * Start a webserver on the given port.
  *
+ * @param flags combination of MHD_FLAG values
  * @param port port to bind to
  * @param apc callback to call to check which clients
  *        will be allowed to connect
  * @param apc_cls extra argument to apc
  * @param dh default handler for all URIs
  * @param dh_cls extra argument to dh
+ * @param ap list of options (type-value pairs,
+ *        terminated with MHD_OPTION_END).
  * @return NULL on error, handle to daemon on success
  */
 struct MHD_Daemon *
-MHD_start_daemon_va (unsigned int options,
+MHD_start_daemon_va (unsigned int flags,
                      uint16_t port,
                      MHD_AcceptPolicyCallback apc,
                      void *apc_cls,
@@ -2193,15 +2193,15 @@ MHD_start_daemon_va (unsigned int options,
   int use_pipe;
 
 #ifndef HAVE_INET6
-  if (0 != (options & MHD_USE_IPv6))
+  if (0 != (flags & MHD_USE_IPv6))
     return NULL;    
 #endif
 #ifndef HAVE_POLL_H
-  if (0 != (options & MHD_USE_POLL))
+  if (0 != (flags & MHD_USE_POLL))
     return NULL;    
 #endif
 #if ! HTTPS_SUPPORT
-  if (0 != (options & MHD_USE_SSL))
+  if (0 != (flags & MHD_USE_SSL))
     return NULL;    
 #endif
   if (NULL == dh)
@@ -2211,7 +2211,7 @@ MHD_start_daemon_va (unsigned int options,
   memset (daemon, 0, sizeof (struct MHD_Daemon));
   /* try to open listen socket */
 #if HTTPS_SUPPORT
-  if (0 != (options & MHD_USE_SSL))
+  if (0 != (flags & MHD_USE_SSL))
     {
       gnutls_priority_init (&daemon->priority_cache,
 			    "NORMAL",
@@ -2219,7 +2219,7 @@ MHD_start_daemon_va (unsigned int options,
     }
 #endif
   daemon->socket_fd = -1;
-  daemon->options = (enum MHD_OPTION) options;
+  daemon->options = (enum MHD_OPTION) flags;
   daemon->port = port;
   daemon->apc = apc;
   daemon->apc_cls = apc_cls;
@@ -2252,7 +2252,7 @@ MHD_start_daemon_va (unsigned int options,
       return NULL;
     }
 #ifndef WINDOWS
-  if ( (0 == (options & MHD_USE_POLL)) &&
+  if ( (0 == (flags & MHD_USE_POLL)) &&
        (daemon->wpipe[0] >= FD_SETSIZE) )
     {
 #if HAVE_MESSAGES
@@ -2271,7 +2271,7 @@ MHD_start_daemon_va (unsigned int options,
   daemon->nonce_nc_size = 4; /* tiny */
 #endif
 #if HTTPS_SUPPORT
-  if (0 != (options & MHD_USE_SSL))
+  if (0 != (flags & MHD_USE_SSL))
     {
       daemon->cred_type = GNUTLS_CRD_CERTIFICATE;
     }
@@ -2281,7 +2281,7 @@ MHD_start_daemon_va (unsigned int options,
   if (MHD_YES != parse_options_va (daemon, &servaddr, ap))
     {
 #if HTTPS_SUPPORT
-      if ( (0 != (options & MHD_USE_SSL)) &&
+      if ( (0 != (flags & MHD_USE_SSL)) &&
 	   (NULL != daemon->priority_cache) )
 	gnutls_priority_deinit (daemon->priority_cache);
 #endif
@@ -2299,7 +2299,7 @@ MHD_start_daemon_va (unsigned int options,
 		    "Specified value for NC_SIZE too large\n");
 #endif
 #if HTTPS_SUPPORT
-	  if (0 != (options & MHD_USE_SSL))
+	  if (0 != (flags & MHD_USE_SSL))
 	    gnutls_priority_deinit (daemon->priority_cache);
 #endif
 	  free (daemon);
@@ -2314,7 +2314,7 @@ MHD_start_daemon_va (unsigned int options,
 		    STRERROR (errno));
 #endif
 #if HTTPS_SUPPORT
-	  if (0 != (options & MHD_USE_SSL))
+	  if (0 != (flags & MHD_USE_SSL))
 	    gnutls_priority_deinit (daemon->priority_cache);
 #endif
 	  free (daemon);
@@ -2329,7 +2329,7 @@ MHD_start_daemon_va (unsigned int options,
 		"MHD failed to initialize nonce-nc mutex\n");
 #endif
 #if HTTPS_SUPPORT
-      if (0 != (options & MHD_USE_SSL))
+      if (0 != (flags & MHD_USE_SSL))
 	gnutls_priority_deinit (daemon->priority_cache);
 #endif
       free (daemon->nnc);
@@ -2339,7 +2339,7 @@ MHD_start_daemon_va (unsigned int options,
 #endif
 
   /* Thread pooling currently works only with internal select thread model */
-  if ( (0 == (options & MHD_USE_SELECT_INTERNALLY)) && 
+  if ( (0 == (flags & MHD_USE_SELECT_INTERNALLY)) && 
        (daemon->worker_pool_size > 0) )
     {
 #if HAVE_MESSAGES
@@ -2350,7 +2350,7 @@ MHD_start_daemon_va (unsigned int options,
     }
 
 #ifdef __SYMBIAN32__
-  if (0 != (options & (MHD_USE_SELECT_INTERNALLY | MHD_USE_THREAD_PER_CONNECTION)))
+  if (0 != (flags & (MHD_USE_SELECT_INTERNALLY | MHD_USE_THREAD_PER_CONNECTION)))
     {
 #if HAVE_MESSAGES
       MHD_DLOG (daemon,
@@ -2363,14 +2363,14 @@ MHD_start_daemon_va (unsigned int options,
        (0 == (daemon->options & MHD_USE_NO_LISTEN_SOCKET)) )
     {
       /* try to open listen socket */
-      if ((options & MHD_USE_IPv6) != 0)
+      if ((flags & MHD_USE_IPv6) != 0)
 	socket_fd = create_socket (PF_INET6, SOCK_STREAM, 0);
       else
 	socket_fd = create_socket (PF_INET, SOCK_STREAM, 0);
       if (-1 == socket_fd)
 	{
 #if HAVE_MESSAGES
-	  if (0 != (options & MHD_USE_DEBUG))
+	  if (0 != (flags & MHD_USE_DEBUG))
 	    MHD_DLOG (daemon, 
 		      "Call to socket failed: %s\n", 
 		      STRERROR (errno));
@@ -2380,7 +2380,7 @@ MHD_start_daemon_va (unsigned int options,
       if ((SETSOCKOPT (socket_fd,
 		       SOL_SOCKET,
 		       SO_REUSEADDR,
-		       &on, sizeof (on)) < 0) && ((options & MHD_USE_DEBUG) != 0))
+		       &on, sizeof (on)) < 0) && ((flags & MHD_USE_DEBUG) != 0))
 	{
 #if HAVE_MESSAGES
 	  MHD_DLOG (daemon, 
@@ -2391,7 +2391,7 @@ MHD_start_daemon_va (unsigned int options,
       
       /* check for user supplied sockaddr */
 #if HAVE_INET6
-      if (0 != (options & MHD_USE_IPv6))
+      if (0 != (flags & MHD_USE_IPv6))
 	addrlen = sizeof (struct sockaddr_in6);
       else
 #endif
@@ -2399,7 +2399,7 @@ MHD_start_daemon_va (unsigned int options,
       if (NULL == servaddr)
 	{
 #if HAVE_INET6
-	  if (0 != (options & MHD_USE_IPv6))
+	  if (0 != (flags & MHD_USE_IPv6))
 	    {
 	      memset (&servaddr6, 0, sizeof (struct sockaddr_in6));
 	      servaddr6.sin6_family = AF_INET6;
@@ -2423,7 +2423,7 @@ MHD_start_daemon_va (unsigned int options,
 	}
       daemon->socket_fd = socket_fd;
 
-      if (0 != (options & MHD_USE_IPv6))
+      if (0 != (flags & MHD_USE_IPv6))
 	{
 #ifdef IPPROTO_IPV6
 #ifdef IPV6_V6ONLY
@@ -2448,7 +2448,7 @@ MHD_start_daemon_va (unsigned int options,
       if (-1 == BIND (socket_fd, servaddr, addrlen))
 	{
 #if HAVE_MESSAGES
-	  if (0 != (options & MHD_USE_DEBUG))
+	  if (0 != (flags & MHD_USE_DEBUG))
 	    MHD_DLOG (daemon,
 		      "Failed to bind to port %u: %s\n", 
 		      (unsigned int) port, 
@@ -2461,7 +2461,7 @@ MHD_start_daemon_va (unsigned int options,
       if (LISTEN (socket_fd, 20) < 0)
 	{
 #if HAVE_MESSAGES
-	  if (0 != (options & MHD_USE_DEBUG))
+	  if (0 != (flags & MHD_USE_DEBUG))
 	    MHD_DLOG (daemon,
 		      "Failed to listen for connections: %s\n", 
 		      STRERROR (errno));
@@ -2476,10 +2476,10 @@ MHD_start_daemon_va (unsigned int options,
     }
 #ifndef WINDOWS
   if ( (socket_fd >= FD_SETSIZE) &&
-       (0 == (options & MHD_USE_POLL)) )
+       (0 == (flags & MHD_USE_POLL)) )
     {
 #if HAVE_MESSAGES
-      if ((options & MHD_USE_DEBUG) != 0)
+      if ((flags & MHD_USE_DEBUG) != 0)
         MHD_DLOG (daemon,
 		  "Socket descriptor larger than FD_SETSIZE: %d > %d\n",
 		  socket_fd,
@@ -2514,7 +2514,7 @@ MHD_start_daemon_va (unsigned int options,
 
 #if HTTPS_SUPPORT
   /* initialize HTTPS daemon certificate aspects & send / recv functions */
-  if ((0 != (options & MHD_USE_SSL)) && (0 != MHD_TLS_init (daemon)))
+  if ((0 != (flags & MHD_USE_SSL)) && (0 != MHD_TLS_init (daemon)))
     {
 #if HAVE_MESSAGES
       MHD_DLOG (daemon, 
@@ -2527,8 +2527,8 @@ MHD_start_daemon_va (unsigned int options,
       goto free_and_fail;
     }
 #endif
-  if ( ( (0 != (options & MHD_USE_THREAD_PER_CONNECTION)) ||
-	 ( (0 != (options & MHD_USE_SELECT_INTERNALLY)) &&
+  if ( ( (0 != (flags & MHD_USE_THREAD_PER_CONNECTION)) ||
+	 ( (0 != (flags & MHD_USE_SELECT_INTERNALLY)) &&
 	   (0 == daemon->worker_pool_size)) ) && 
        (0 == (daemon->options & MHD_USE_NO_LISTEN_SOCKET)) &&
        (0 != (res_thread_create =
@@ -2671,7 +2671,7 @@ thread_failed:
   pthread_mutex_destroy (&daemon->nnc_lock);
 #endif
 #if HTTPS_SUPPORT
-  if (0 != (options & MHD_USE_SSL))
+  if (0 != (flags & MHD_USE_SSL))
     gnutls_priority_deinit (daemon->priority_cache);
 #endif
   free (daemon);

src/daemon/digestauth.c

@@ -736,6 +736,9 @@ MHD_digest_auth_check (struct MHD_Connection *connection,
  * @param connection The MHD connection structure
  * @param realm the realm presented to the client
  * @param opaque string to user for opaque value
+ * @param response reply to send; should contain the "access denied"
+ *        body; note that this function will set the "WWW Authenticate"
+ *        header and that the caller should not do this
  * @param signal_stale MHD_YES if the nonce is invalid to add
  * 			'stale=true' to the authentication header
  * @return MHD_YES on success, MHD_NO otherwise

src/daemon/internal.c

@@ -111,6 +111,7 @@ MHD_DLOG (const struct MHD_Daemon *daemon, const char *format, ...)
  *
  * @param cls closure (use NULL)
  * @param connection handle to connection, not used
+ * @param val value to unescape (modified in the process)
  * @return length of the resulting val (strlen(val) maybe
  *  shorter afterwards due to elimination of escape sequences)
  */

src/daemon/internal.h

@@ -57,14 +57,14 @@ extern void *mhd_panic_cls;
 /**
  * Trigger 'panic' action based on fatal errors.
  * 
- * @param error message (const char *)
+ * @param msg error message (const char *)
  */
 #define MHD_PANIC(msg) mhd_panic (mhd_panic_cls, __FILE__, __LINE__, msg)
 #else
 /**
  * Trigger 'panic' action based on fatal errors.
  * 
- * @param error message (const char *)
+ * @param msg error message (const char *)
  */
 #define MHD_PANIC(msg) mhd_panic (mhd_panic_cls, __FILE__, __LINE__, NULL)
 #endif
@@ -156,6 +156,7 @@ MHD_DLOG (const struct MHD_Daemon *daemon,
  *
  * @param cls closure (use NULL)
  * @param connection handle to connection, not used
+ * @param val value to unescape (modified in the process)
  * @return length of the resulting val (strlen(val) maybe
  *  shorter afterwards due to elimination of escape sequences)
  */

src/daemon/memorypool.c

@@ -81,6 +81,7 @@ struct MemoryPool
  * Create a memory pool.
  *
  * @param max maximum size of the pool
+ * @return NULL on error
  */
 struct MemoryPool *
 MHD_pool_create (size_t max)
@@ -119,6 +120,8 @@ MHD_pool_create (size_t max)
 
 /**
  * Destroy a memory pool.
+ *
+ * @param pool memory pool to destroy
  */
 void
 MHD_pool_destroy (struct MemoryPool *pool)
@@ -135,6 +138,12 @@ MHD_pool_destroy (struct MemoryPool *pool)
 
 /**
  * Allocate size bytes from the pool.
+ *
+ * @param pool memory pool to use for the operation
+ * @param size number of bytes to allocate
+ * @param from_end allocate from end of pool (set to MHD_YES);
+ *        use this for small, persistent allocations that
+ *        will never be reallocated
  * @return NULL if the pool cannot support size more
  *         bytes
  */
@@ -170,6 +179,7 @@ MHD_pool_allocate (struct MemoryPool *pool,
  * allocation may be leaked until the pool is
  * destroyed (and copying the data maybe required).
  *
+ * @param pool memory pool to use for the operation
  * @param old the existing block
  * @param old_size the size of the existing block
  * @param new_size the new size of the block
@@ -223,6 +233,7 @@ MHD_pool_reallocate (struct MemoryPool *pool,
  * Clear all entries from the memory pool except
  * for "keep" of the given "size".
  *
+ * @param pool memory pool to use for the operation
  * @param keep pointer to the entry to keep (maybe NULL)
  * @param size how many bytes need to be kept at this address
  * @return addr new address of "keep" (if it had to change)

src/daemon/memorypool.h

@@ -42,6 +42,7 @@ struct MemoryPool;
  * Create a memory pool.
  *
  * @param max maximum size of the pool
+ * @return NULL on error
  */
 struct MemoryPool *
 MHD_pool_create (size_t max);
@@ -49,6 +50,8 @@ MHD_pool_create (size_t max);
 
 /**
  * Destroy a memory pool.
+ *
+ * @param pool memory pool to destroy
  */
 void 
 MHD_pool_destroy (struct MemoryPool *pool);
@@ -57,6 +60,8 @@ MHD_pool_destroy (struct MemoryPool *pool);
 /**
  * Allocate size bytes from the pool.
  *
+ * @param pool memory pool to use for the operation
+ * @param size number of bytes to allocate
  * @param from_end allocate from end of pool (set to MHD_YES);
  *        use this for small, persistent allocations that
  *        will never be reallocated
@@ -77,6 +82,7 @@ MHD_pool_allocate (struct MemoryPool *pool,
  * allocation may be leaked until the pool is
  * destroyed (and copying the data maybe required).
  *
+ * @param pool memory pool to use for the operation
  * @param old the existing block
  * @param old_size the size of the existing block
  * @param new_size the new size of the block
@@ -95,6 +101,7 @@ MHD_pool_reallocate (struct MemoryPool *pool,
  * Clear all entries from the memory pool except
  * for "keep" of the given "size".
  *
+ * @param pool memory pool to use for the operation
  * @param keep pointer to the entry to keep (maybe NULL)
  * @param size how many bytes need to be kept at this address
  * @return addr new address of "keep" (if it had to change)

src/daemon/postprocessor.c

@@ -71,19 +71,19 @@ enum RN_State
   RN_Inactive = 0,
 
   /**
-   * If the next character is '\n', skip it.  Otherwise,
+   * If the next character is CR, skip it.  Otherwise,
    * just go inactive.
    */
   RN_OptN = 1,
 
   /**
-   * Expect '\r\n' (and only '\r\n').  As always, we also
-   * expect only '\r' or only '\n'.
+   * Expect LFCR (and only LFCR).  As always, we also
+   * expect only LF or only CR.
    */
   RN_Full = 2,
 
   /**
-   * Expect either '\r\n' or '--\r\n'.  If '--\r\n', transition into dash-state
+   * Expect either LFCR or '--'LFCR.  If '--'LFCR, transition into dash-state
    * for the main state machine
    */
   RN_Dash = 3,
@@ -221,9 +221,9 @@ struct MHD_PostProcessor
   enum PP_State state;
 
   /**
-   * Side-state-machine: skip '\r\n' (or just '\n').
+   * Side-state-machine: skip LRCR (or just LF).
    * Set to 0 if we are not in skip mode.  Set to 2
-   * if a '\r\n' is expected, set to 1 if a '\n' should
+   * if a LFCR is expected, set to 1 if a CR should
    * be skipped if it is the next character.
    */
   enum RN_State skip_rn;
@@ -256,22 +256,22 @@ struct MHD_PostProcessor
  *        specifically the parsing of the keys).  A
  *        tiny value (256-1024) should be sufficient.
  *        Do NOT use 0.
- * @param ikvi iterator to be called with the parsed data
- * @param cls first argument to ikvi
+ * @param iter iterator to be called with the parsed data
+ * @param iter_cls first argument to iter
  * @return NULL on error (out of memory, unsupported encoding),
  *         otherwise a PP handle
  */
 struct MHD_PostProcessor *
 MHD_create_post_processor (struct MHD_Connection *connection,
                            size_t buffer_size,
-                           MHD_PostDataIterator ikvi, void *cls)
+                           MHD_PostDataIterator iter, void *iter_cls)
 {
   struct MHD_PostProcessor *ret;
   const char *encoding;
   const char *boundary;
   size_t blen;
 
-  if ((buffer_size < 256) || (connection == NULL) || (ikvi == NULL))
+  if ((buffer_size < 256) || (connection == NULL) || (iter == NULL))
     mhd_panic (mhd_panic_cls, __FILE__, __LINE__, NULL);
   encoding = MHD_lookup_connection_value (connection,
                                           MHD_HEADER_KIND,
@@ -312,8 +312,8 @@ MHD_create_post_processor (struct MHD_Connection *connection,
     return NULL;
   memset (ret, 0, sizeof (struct MHD_PostProcessor) + buffer_size + 1);
   ret->connection = connection;
-  ret->ikvi = ikvi;
-  ret->cls = cls;
+  ret->ikvi = iter;
+  ret->cls = iter_cls;
   ret->encoding = encoding;
   ret->buffer_size = buffer_size;
   ret->state = PP_Init;
@@ -508,6 +508,15 @@ try_match_header (const char *prefix, char *line, char **suffix)
 /**
  *
  * @param pp post processor context
+ * @param boundary boundary to look for
+ * @param blen number of bytes in boundary
+ * @param ioffptr set to the end of the boundary if found,
+ *                otherwise incremented by one (FIXME: quirky API!)
+ * @param next_state state to which we should advance the post processor
+ *                   if the boundary is found
+ * @param next_dash_state dash_state to which we should advance the
+ *                   post processor if the boundary is found
+ * @return MHD_NO if the boundary is not found, MHD_YES if we did find it
  */
 static int
 find_boundary (struct MHD_PostProcessor *pp,
@@ -595,6 +604,8 @@ try_get_value (const char *buf,
  * @param pp post processor context
  * @param ioffptr set to how many bytes have been
  *                processed
+ * @param next_state state to which the post processor should
+ *                be advanced if we find the end of the headers
  * @return MHD_YES if we can continue processing,
  *         MHD_NO on error or if we do not have
  *                enough data yet
@@ -617,7 +628,7 @@ process_multipart_headers (struct MHD_PostProcessor *pp,
     }
   if (newline == pp->buffer_pos)
     return MHD_NO;              /* will need more data */
-  if (newline == 0)
+  if (0 == newline)
     {
       /* empty line - end of headers */
       pp->skip_rn = RN_Full;
@@ -652,6 +663,7 @@ process_multipart_headers (struct MHD_PostProcessor *pp,
  * process accordingly.
  *
  * @param pp post processor context
+ * @param ioffptr incremented based on the number of bytes processed
  * @param boundary the boundary to look for
  * @param blen strlen(boundary)
  * @param next_state what state to go into after the
@@ -707,7 +719,7 @@ process_value_to_boundary (struct MHD_PostProcessor *pp,
           /* cannot check for boundary, process content that
              we have and check again later; except, if we have
              no content, abort (out of memory) */
-          if ((newline == 0) && (pp->buffer_pos == pp->buffer_size))
+          if ((0 == newline) && (pp->buffer_pos == pp->buffer_size))
             {
               pp->state = PP_Error;
               return MHD_NO;
@@ -745,23 +757,23 @@ process_value_to_boundary (struct MHD_PostProcessor *pp,
 static void
 free_unmarked (struct MHD_PostProcessor *pp)
 {
-  if ((pp->content_name != NULL) && (0 == (pp->have & NE_content_name)))
+  if ((NULL != pp->content_name) && (0 == (pp->have & NE_content_name)))
     {
       free (pp->content_name);
       pp->content_name = NULL;
     }
-  if ((pp->content_type != NULL) && (0 == (pp->have & NE_content_type)))
+  if ((NULL != pp->content_type) && (0 == (pp->have & NE_content_type)))
     {
       free (pp->content_type);
       pp->content_type = NULL;
     }
-  if ((pp->content_filename != NULL) &&
+  if ((NULL != pp->content_filename) &&
       (0 == (pp->have & NE_content_filename)))
     {
       free (pp->content_filename);
       pp->content_filename = NULL;
     }
-  if ((pp->content_transfer_encoding != NULL) &&
+  if ((NULL != pp->content_transfer_encoding) &&
       (0 == (pp->have & NE_content_transfer_encoding)))
     {
       free (pp->content_transfer_encoding);
@@ -774,6 +786,9 @@ free_unmarked (struct MHD_PostProcessor *pp)
  * Decode multipart POST data.
  *
  * @param pp post processor context
+ * @param post_data data to decode
+ * @param post_data_len number of bytes in 'post_data'
+ * @return MHD_NO on error, 
  */
 static int
 post_process_multipart (struct MHD_PostProcessor *pp,

src/daemon/response.c

@@ -158,6 +158,7 @@ MHD_del_response_header (struct MHD_Response *response,
 /**
  * Get all of the headers added to a response.
  *
+ * @param response response to query
  * @param iterator callback to call on each header;
  *        maybe NULL (then just count headers)
  * @param iterator_cls extra argument to iterator
@@ -185,11 +186,13 @@ MHD_get_response_headers (struct MHD_Response *response,
 /**
  * Get a particular header from the response.
  *
+ * @param response response to query
  * @param key which header to get
  * @return NULL if header does not exist
  */
 const char *
-MHD_get_response_header (struct MHD_Response *response, const char *key)
+MHD_get_response_header (struct MHD_Response *response, 
+			 const char *key)
 {
   struct MHD_HTTP_Header *pos;
 
@@ -296,7 +299,7 @@ free_callback (void *cls)
  *
  * @param size size of the data portion of the response
  * @param fd file descriptor referring to a file on disk with the data
- * @param off offset to start reading from in the file
+ * @param offset offset to start reading from in the file
  * @return NULL on error (i.e. invalid arguments, out of memory)
  */
 struct MHD_Response *MHD_create_response_from_fd_at_offset (size_t size,

src/daemon/test_daemon.c

@@ -19,7 +19,7 @@
 */
 
 /**
- * @file daemon_test.c
+ * @file test_daemon.c
  * @brief  Testcase for libmicrohttpd starts and stops
  * @author Christian Grothoff
  */

src/daemon/test_postprocessor.c

@@ -19,7 +19,7 @@
 */
 
 /**
- * @file postprocessor_test.c
+ * @file test_postprocessor.c
  * @brief  Testcase for postprocessor
  * @author Christian Grothoff
  */

src/daemon/test_postprocessor_large.c

@@ -19,7 +19,7 @@
 */
 
 /**
- * @file postprocessor_large_test.c
+ * @file test_postprocessor_large.c
  * @brief  Testcase with very large input for postprocessor
  * @author Christian Grothoff
  */

src/examples/https_fileserver_example.c

@@ -17,7 +17,7 @@
      Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */
 /**
- * @file https_server_example.c
+ * @file https_fileserver_example.c
  * @brief a simple HTTPS file server using TLS.
  *
  * Usage :

src/examples/post_example.c

@@ -492,9 +492,9 @@ post_iterator (void *cls,
 /**
  * Main MHD callback for handling requests.
  *
- *
  * @param cls argument given together with the function
  *        pointer when the handler was registered with MHD
+ * @param connection handle identifying the incoming connection
  * @param url the requested url
  * @param method the HTTP method used ("GET", "PUT", etc.)
  * @param version the HTTP version string (i.e. "HTTP/1.1")
@@ -508,7 +508,7 @@ post_iterator (void *cls,
  * @param upload_data_size set initially to the size of the
  *        upload_data provided; the method must update this
  *        value to the number of bytes NOT processed;
- * @param con_cls pointer that the callback can set to some
+ * @param ptr pointer that the callback can set to some
  *        address and that will be preserved by MHD for future
  *        calls for this request; since the access handler may
  *        be called many times (i.e., for a PUT/POST operation

src/include/microhttpd.h

@@ -66,7 +66,7 @@
  * "platform.h" in the MHD distribution).  If you have done so, you
  * should also have a line with "#define MHD_PLATFORM_H" which will
  * prevent this header from trying (and, depending on your platform,
- * failing) to #include the right headers.
+ * failing) to include the right headers.
  */
 
 #ifndef MHD_MICROHTTPD_H
@@ -1066,12 +1066,12 @@ typedef int
  * @param apc_cls extra argument to apc
  * @param dh handler called for all requests (repeatedly)
  * @param dh_cls extra argument to dh
- * @param ... list of options (type-value pairs,
+ * @param ap list of options (type-value pairs,
  *        terminated with MHD_OPTION_END).
  * @return NULL on error, handle to daemon on success
  */
 struct MHD_Daemon *
-MHD_start_daemon_va (unsigned int options,
+MHD_start_daemon_va (unsigned int flags,
 		     uint16_t port,
 		     MHD_AcceptPolicyCallback apc, void *apc_cls,
 		     MHD_AccessHandlerCallback dh, void *dh_cls, 
@@ -1458,7 +1458,7 @@ MHD_create_response_from_fd (size_t size,
  * @param fd file descriptor referring to a file on disk with the
  *        data; will be closed when response is destroyed;
  *        fd should be in 'blocking' mode
- * @param off offset to start reading from in the file;
+ * @param offset offset to start reading from in the file;
  *        Be careful! 'off_t' may have been compiled to be a 
  *        64-bit variable for MHD, in which case your application
  *        also has to be compiled using the same options! Read
@@ -1655,6 +1655,7 @@ int
 MHD_del_response_header (struct MHD_Response *response,
                          const char *header, const char *content);
 
+
 /**
  * Get all of the headers (and footers) added to a response.
  *
@@ -1702,14 +1703,14 @@ const char *MHD_get_response_header (struct MHD_Response *response,
  *        performance, use 32 or 64k (i.e. 65536).
  * @param iter iterator to be called with the parsed data,
  *        Must NOT be NULL.
- * @param cls first argument to ikvi
+ * @param iter_cls first argument to iter
  * @return  NULL on error (out of memory, unsupported encoding),
  *          otherwise a PP handle
  */
 struct MHD_PostProcessor *
 MHD_create_post_processor (struct MHD_Connection *connection,
 			   size_t buffer_size,
-			   MHD_PostDataIterator iter, void *cls);
+			   MHD_PostDataIterator iter, void *iter_cls);
 
 /**
  * Parse and process POST data.
@@ -1818,9 +1819,13 @@ MHD_basic_auth_get_username_password (struct MHD_Connection *connection,
 
 /**
  * Queues a response to request basic authentication from the client
+ * The given response object is expected to include the payload for
+ * the response; the "WWW-Authenticate" header will be added and the
+ * response queued with the 'UNAUTHORIZED' status code.
  *
  * @param connection The MHD connection structure
  * @param realm the realm presented to the client
+ * @param response response object to modify and queue
  * @return MHD_YES on success, MHD_NO otherwise
  */
 int

src/include/plibc/plibc.h

@@ -18,7 +18,7 @@
 */
 
 /**
- * @file include/plibc.h
+ * @file plibc.h
  * @brief PlibC header
  * @attention This file is usually not installed under Unix,
  *            so ship it with your application

src/testcurl/https/tls_test_common.c

@@ -252,10 +252,13 @@ send_curl_req (char *url, struct CBC * cbc, const char *cipher_suite,
   return CURLE_OK;
 }
 
+
 /**
  * compile test file url pointing to the current running directory path
+ *
  * @param url - char buffer into which the url is compiled
- * @return
+ * @param port port to use for the test
+ * @return -1 on error
  */
 int
 gen_test_file_url (char *url, int port)

src/testcurl/https/tls_test_common.h

@@ -98,6 +98,14 @@ http_dummy_ahc (void *cls, struct MHD_Connection *connection,
                 const char *version, size_t *upload_data_size,
                 void **ptr);
 
+
+/**
+ * compile test file url pointing to the current running directory path
+ *
+ * @param url - char buffer into which the url is compiled
+ * @param port port to use for the test
+ * @return -1 on error
+ */
 int gen_test_file_url (char *url, int port);
 
 int