-more doxygen improvements

configure.ac

@@ -556,6 +556,7 @@ libmicrohttpd.pc
 Makefile
 contrib/Makefile
 doc/Makefile
+doc/doxygen/Makefile
 doc/examples/Makefile
 m4/Makefile
 src/Makefile

doc/Makefile.am

@@ -25,5 +25,5 @@ microhttpd_TEXINFOS = \
   lgpl.texi \
   ecos.texi
 
-EXTRA_DIST = $(man_MANS) Doxyfile $(microhttpd_TEXINFOS) 
+EXTRA_DIST = $(man_MANS) $(microhttpd_TEXINFOS) 
 

doc/doxygen/Makefile.am

@@ -0,0 +1,17 @@
+all:
+	@echo -e \
+"Generate documentation:\n" \
+"\tmake full - full documentation with dependency graphs (slow)\n" \
+"\tmake fast - fast mode without dependency graphs"
+
+full: libmicrohttpd.doxy
+	doxygen $<
+
+fast: libmicrohttpd.doxy
+	sed 's/\(HAVE_DOT.*=\).*/\1 NO/' $< | doxygen -
+
+clean:
+	rm -rf html
+
+
+EXTRA_DIST = libmicrohttpd.doxy

doc/Doxyfile → doc/doxygen/libmicrohttpd.doxy

@@ -5,8 +5,8 @@
 #---------------------------------------------------------------------------
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "GNU libmicrohttpd"
-PROJECT_NUMBER         = 0.9.5
-OUTPUT_DIRECTORY       = doc/doxygen/
+PROJECT_NUMBER         = 0.9.29
+OUTPUT_DIRECTORY       = .
 CREATE_SUBDIRS         = YES
 OUTPUT_LANGUAGE        = English
 BRIEF_MEMBER_DESC      = YES
@@ -25,8 +25,9 @@ ABBREVIATE_BRIEF       = "The $name class" \
 ALWAYS_DETAILED_SEC    = NO
 INLINE_INHERITED_MEMB  = NO
 FULL_PATH_NAMES        = YES
-STRIP_FROM_PATH        = /home/grothoff/svn/libmicrohttpd/
-STRIP_FROM_INC_PATH    = 
+STRIP_FROM_PATH        = ../..
+STRIP_FROM_INC_PATH    = ../../src/include \
+		         src/include
 SHORT_NAMES            = NO
 JAVADOC_AUTOBRIEF      = NO
 QT_AUTOBRIEF           = NO
@@ -90,16 +91,14 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = /home/grothoff/svn/libmicrohttpd/src/include \
-                         /home/grothoff/svn/libmicrohttpd/src/daemon
+INPUT                  = ../..
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = *.c \
                          *.h
 RECURSIVE              = YES
-EXCLUDE                = /home/grothoff/svn/libmicrohttpd/src/daemon/daemon_test.c \
-                         /home/grothoff/svn/libmicrohttpd/src/daemon/postprocessor_test.c
+EXCLUDE                = 
 EXCLUDE_SYMLINKS       = NO
-EXCLUDE_PATTERNS       = 
+EXCLUDE_PATTERNS       = */test_* */.svn/* */perf_*
 EXCLUDE_SYMBOLS        = MHD_DLOG
 EXAMPLE_PATH           = 
 EXAMPLE_PATTERNS       = *
@@ -249,4 +248,4 @@ DOT_CLEANUP            = YES
 #---------------------------------------------------------------------------
 # Configuration::additions related to the search engine   
 #---------------------------------------------------------------------------
-SEARCHENGINE           = NO
+SEARCHENGINE           = YES

src/microhttpd/basicauth.c

@@ -40,10 +40,11 @@
  * @param password a pointer for the password
  * @return NULL if no username could be found, a pointer
  * 			to the username if found
+ * @ingroup authentication
  */
 char *
-MHD_basic_auth_get_username_password(struct MHD_Connection *connection,
-				     char** password) 
+MHD_basic_auth_get_username_password (struct MHD_Connection *connection,
+				      char** password) 
 {
   const char *header;
   char *decode;
@@ -108,7 +109,8 @@ MHD_basic_auth_get_username_password(struct MHD_Connection *connection,
  * @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
+ * @return #MHD_YES on success, #MHD_NO otherwise
+ * @ingroup authentication
  */
 int 
 MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection,

src/microhttpd/connection.c

@@ -113,8 +113,9 @@
  * @param kind types of values to iterate over
  * @param iterator callback to call on each header;
  *        maybe NULL (then just count headers)
- * @param iterator_cls extra argument to iterator
+ * @param iterator_cls extra argument to @a iterator
  * @return number of entries iterated over
+ * @ingroup request
  */
 int
 MHD_get_connection_values (struct MHD_Connection *connection,
@@ -141,15 +142,15 @@ MHD_get_connection_values (struct MHD_Connection *connection,
 
 
 /**
- * This function can be used to append an entry to the list of HTTP
- * headers of a connection (so that the MHD_get_connection_values
- * function will return them -- and the MHD PostProcessor will also
- * see them).  This maybe required in certain situations (see Mantis
+ * This function can be used to add an entry to the HTTP headers of a
+ * connection (so that the #MHD_get_connection_values function will
+ * return them -- and the `struct MHD_PostProcessor` will also see
+ * them).  This maybe required in certain situations (see Mantis
  * #1399) where (broken) HTTP implementations fail to supply values
  * needed by the post processor (or other parts of the application).
- *
+ * 
  * This function MUST only be called from within the
- * MHD_AccessHandlerCallback (otherwise, access maybe improperly
+ * #MHD_AccessHandlerCallback (otherwise, access maybe improperly
  * synchronized).  Furthermore, the client must guarantee that the key
  * and value arguments are 0-terminated strings that are NOT freed
  * until the connection is closed.  (The easiest way to do this is by
@@ -160,9 +161,10 @@ MHD_get_connection_values (struct MHD_Connection *connection,
  * @param kind kind of the value
  * @param key key for the value
  * @param value the value itself
- * @return MHD_NO if the operation could not be
+ * @return #MHD_NO if the operation could not be
  *         performed due to insufficient memory;
- *         MHD_YES on success
+ *         #MHD_YES on success
+ * @ingroup request
  */
 int
 MHD_set_connection_value (struct MHD_Connection *connection,
@@ -202,6 +204,7 @@ MHD_set_connection_value (struct MHD_Connection *connection,
  * @param kind what kind of value are we looking for
  * @param key the header to look for, NULL to lookup 'trailing' value without a key
  * @return NULL if no such item was found
+ * @ingroup request
  */
 const char *
 MHD_lookup_connection_value (struct MHD_Connection *connection,
@@ -2561,15 +2564,16 @@ MHD_set_http_callbacks_ (struct MHD_Connection *connection)
  *
  * @param connection what connection to get information about
  * @param infoType what information is desired?
- * @param ... depends on infoType
+ * @param ... depends on @a info_type
  * @return NULL if this information is not available
- *         (or if the infoType is unknown)
+ *         (or if the @a info_type is unknown)
+ * @ingroup specialized
  */
 const union MHD_ConnectionInfo *
 MHD_get_connection_info (struct MHD_Connection *connection,
-                         enum MHD_ConnectionInfoType infoType, ...)
+                         enum MHD_ConnectionInfoType info_type, ...)
 {
-  switch (infoType)
+  switch (info_type)
     {
 #if HTTPS_SUPPORT
     case MHD_CONNECTION_INFO_CIPHER_ALGO:
@@ -2605,7 +2609,8 @@ MHD_get_connection_info (struct MHD_Connection *connection,
  * @param connection connection to modify
  * @param option option to set
  * @param ... arguments to the option, depending on the option type
- * @return MHD_YES on success, MHD_NO if setting the option failed
+ * @return #MHD_YES on success, #MHD_NO if setting the option failed
+ * @ingroup specialized
  */
 int 
 MHD_set_connection_option (struct MHD_Connection *connection,
@@ -2653,13 +2658,14 @@ MHD_set_connection_option (struct MHD_Connection *connection,
 
 /**
  * Queue a response to be transmitted to the client (as soon as
- * possible but after MHD_AccessHandlerCallback returns).
+ * possible but after #MHD_AccessHandlerCallback returns).
  *
  * @param connection the connection identifying the client
- * @param status_code HTTP status code (i.e. 200 for OK)
+ * @param status_code HTTP status code (i.e. #MHD_HTTP_OK)
  * @param response response to transmit
- * @return MHD_NO on error (i.e. reply already sent),
- *         MHD_YES on success or if message has been queued
+ * @return #MHD_NO on error (i.e. reply already sent),
+ *         #MHD_YES on success or if message has been queued
+ * @ingroup response
  */
 int
 MHD_queue_response (struct MHD_Connection *connection,

src/microhttpd/daemon.c

@@ -548,7 +548,7 @@ add_to_fd_set (int fd,
 
 
 /**
- * Obtain the select sets for this daemon.
+ * Obtain the `select()` sets for this daemon.
  *
  * @param daemon daemon to get sets from
  * @param read_fd_set read set
@@ -556,9 +556,10 @@ add_to_fd_set (int fd,
  * @param except_fd_set except set
  * @param max_fd increased to largest FD added (if larger
  *               than existing value); can be NULL
- * @return MHD_YES on success, MHD_NO if this
+ * @return #MHD_YES on success, #MHD_NO if this
  *         daemon was not started with the right
  *         options for this call.
+ * @ingroup event
  */
 int
 MHD_get_fdset (struct MHD_Daemon *daemon,
@@ -1406,12 +1407,16 @@ make_nonblocking_noninheritable (struct MHD_Daemon *daemon,
 
 
 /**
- * Add another client connection to the set of connections 
- * managed by MHD.  This API is usually not needed (since
- * MHD will accept inbound connections on the server socket).
- * Use this API in special cases, for example if your HTTP
- * server is behind NAT and needs to connect out to the 
- * HTTP client.
+ * Add another client connection to the set of connections managed by
+ * MHD.  This API is usually not needed (since MHD will accept inbound
+ * connections on the server socket).  Use this API in special cases,
+ * for example if your HTTP server is behind NAT and needs to connect
+ * out to the HTTP client, or if you are building a proxy.
+ *
+ * If you use this API in conjunction with a internal select or a
+ * thread pool, you must set the option
+ * #MHD_USE_PIPE_FOR_SHUTDOWN to ensure that the freshly added
+ * connection is immediately processed by MHD.
  *
  * The given client socket will be managed (and closed!) by MHD after
  * this call and must no longer be used directly by the application
@@ -1423,11 +1428,12 @@ make_nonblocking_noninheritable (struct MHD_Daemon *daemon,
  * @param client_socket socket to manage (MHD will expect
  *        to receive an HTTP request from this socket next).
  * @param addr IP address of the client
- * @param addrlen number of bytes in addr
- * @return MHD_YES on success, MHD_NO if this daemon could
- *        not handle the connection (i.e. malloc failed, etc).
- *        The socket will be closed in any case; 'errno' is
+ * @param addrlen number of bytes in @a addr
+ * @return #MHD_YES on success, #MHD_NO if this daemon could
+ *        not handle the connection (i.e. `malloc()` failed, etc).
+ *        The socket will be closed in any case; `errno` is
  *        set to indicate further details about the error.
+ * @ingroup specialized
  */
 int 
 MHD_add_connection (struct MHD_Daemon *daemon, 
@@ -1602,16 +1608,18 @@ MHD_cleanup_connections (struct MHD_Daemon *daemon)
 
 
 /**
- * Obtain timeout value for select for this daemon
- * (only needed if connection timeout is used).  The
- * returned value is how long select should at most
- * block, not the timeout value set for connections.
+ * Obtain timeout value for `select()` for this daemon (only needed if
+ * connection timeout is used).  The returned value is how long
+ * `select()` or `poll()` should at most block, not the timeout value set
+ * for connections.  This function MUST NOT be called if MHD is
+ * running with #MHD_USE_THREAD_PER_CONNECTION.
  *
  * @param daemon daemon to query for timeout
  * @param timeout set to the timeout (in milliseconds)
- * @return MHD_YES on success, MHD_NO if timeouts are
+ * @return #MHD_YES on success, #MHD_NO if timeouts are
  *        not used (or no connections exist that would
  *        necessiate the use of a timeout right now).
+ * @ingroup event
  */
 int
 MHD_get_timeout (struct MHD_Daemon *daemon,
@@ -1685,21 +1693,22 @@ MHD_get_timeout (struct MHD_Daemon *daemon,
 
 /**
  * Run webserver operations. This method should be called by clients
- * in combination with MHD_get_fdset if the client-controlled select
+ * in combination with #MHD_get_fdset if the client-controlled select
  * method is used.
  *
- * You can use this function instead of "MHD_run" if you called
- * 'select' on the result from "MHD_get_fdset".  File descriptors in
+ * You can use this function instead of #MHD_run if you called
+ * `select()` on the result from #MHD_get_fdset.  File descriptors in
  * the sets that are not controlled by MHD will be ignored.  Calling
- * this function instead of "MHD_run" is more efficient as MHD will
- * not have to call 'select' again to determine which operations are
+ * this function instead of #MHD_run is more efficient as MHD will
+ * not have to call `select()` again to determine which operations are
  * ready.
  *
  * @param daemon daemon to run select loop for
  * @param read_fd_set read set
  * @param write_fd_set write set
  * @param except_fd_set except set (not used, can be NULL)
- * @return MHD_NO on serious errors, MHD_YES on success
+ * @return #MHD_NO on serious errors, #MHD_YES on success
+ * @ingroup event
  */
 int
 MHD_run_from_select (struct MHD_Daemon *daemon, 
@@ -2295,18 +2304,23 @@ MHD_epoll (struct MHD_Daemon *daemon,
 
 
 /**
- * Run webserver operations (without blocking unless
- * in client callbacks).  This method should be called
- * by clients in combination with MHD_get_fdset
- * if the client-controlled select method is used.
+ * Run webserver operations (without blocking unless in client
+ * callbacks).  This method should be called by clients in combination
+ * with #MHD_get_fdset if the client-controlled select method is used.
  *
- * This function will work for external 'poll' and 'select' mode.
- * However, if using external 'select' mode, you may want to
- * instead use 'MHD_run_from_select', as it is more efficient.
+ * This function is a convenience method, which is useful if the
+ * fd_sets from #MHD_get_fdset were not directly passed to `select()`;
+ * with this function, MHD will internally do the appropriate `select()`
+ * call itself again.  While it is always safe to call #MHD_run (in
+ * external select mode), you should call #MHD_run_from_select if
+ * performance is important (as it saves an expensive call to
+ * `select()`).
  *
- * @return MHD_YES on success, MHD_NO if this
+ * @param daemon daemon to run
+ * @return #MHD_YES on success, #MHD_NO if this
  *         daemon was not started with the right
  *         options for this call.
+ * @ingroup event
  */
 int
 MHD_run (struct MHD_Daemon *daemon)
@@ -2365,16 +2379,20 @@ MHD_select_thread (void *cls)
 
 
 /**
- * Start a webserver on the given port.
+ * Start a webserver on the given port.  Variadic version of
+ * #MHD_start_daemon_va.
  *
- * @param flags combination of MHD_FLAG values
+ * @param flags combination of `enum MHD_FLAG` values
  * @param port port to bind to
  * @param apc callback to call to check which clients
- *        will be allowed to connect
+ *        will be allowed to connect; you can pass NULL
+ *        in which case connections from any IP will be
+ *        accepted
  * @param apc_cls extra argument to apc
- * @param dh default handler for all URIs
- * @param dh_cls extra argument to dh
+ * @param dh handler called for all requests (repeatedly)
+ * @param dh_cls extra argument to @a dh
  * @return NULL on error, handle to daemon on success
+ * @ingroup event
  */
 struct MHD_Daemon *
 MHD_start_daemon (unsigned int flags,
@@ -2399,12 +2417,18 @@ MHD_start_daemon (unsigned int flags,
  * connections.  Note that the caller is responsible for closing the
  * returned socket; however, if MHD is run using threads (anything but
  * external select mode), it must not be closed until AFTER
- * "MHD_stop_daemon" has been called (as it is theoretically possible
+ * #MHD_stop_daemon has been called (as it is theoretically possible
  * that an existing thread is still using it).
  *
+ * Note that some thread modes require the caller to have passed
+ * #MHD_USE_PIPE_FOR_SHUTDOWN when using this API.  If this daemon is
+ * in one of those modes and this option was not given to
+ * #MHD_start_daemon, this function will return -1.
+ *
  * @param daemon daemon to stop accepting new connections for
  * @return old listen socket on success, -1 if the daemon was 
  *         already not listening anymore
+ * @ingroup specialized
  */
 int
 MHD_quiesce_daemon (struct MHD_Daemon *daemon)
@@ -2877,20 +2901,22 @@ setup_epoll_to_listen (struct MHD_Daemon *daemon)
 #endif
 
 
-
 /**
  * Start a webserver on the given port.
  *
- * @param flags combination of MHD_FLAG values
- * @param port port to bind to
+ * @param flags combination of `enum MHD_FLAG` values
+ * @param port port to bind to (in host byte order)
  * @param apc callback to call to check which clients
- *        will be allowed to connect
+ *        will be allowed to connect; you can pass NULL
+ *        in which case connections from any IP will be
+ *        accepted
  * @param apc_cls extra argument to apc
- * @param dh default handler for all URIs
- * @param dh_cls extra argument to dh
+ * @param dh handler called for all requests (repeatedly)
+ * @param dh_cls extra argument to @a dh
  * @param ap list of options (type-value pairs,
- *        terminated with MHD_OPTION_END).
+ *        terminated with #MHD_OPTION_END).
  * @return NULL on error, handle to daemon on success
+ * @ingroup event
  */
 struct MHD_Daemon *
 MHD_start_daemon_va (unsigned int flags,
@@ -3587,9 +3613,10 @@ epoll_shutdown (struct MHD_Daemon *daemon)
 
 
 /**
- * Shutdown an http daemon
+ * Shutdown an HTTP daemon.
  *
  * @param daemon daemon to stop
+ * @ingroup event
  */
 void
 MHD_stop_daemon (struct MHD_Daemon *daemon)
@@ -3722,16 +3749,18 @@ MHD_stop_daemon (struct MHD_Daemon *daemon)
  * (not fully implemented!).
  *
  * @param daemon what daemon to get information about
- * @param infoType what information is desired?
- * @param ... depends on infoType
+ * @param info_type what information is desired?
+ * @param ... depends on @a info_type
  * @return NULL if this information is not available
- *         (or if the infoType is unknown)
+ *         (or if the @a info_type is unknown)
+ * @ingroup specialized
  */
 const union MHD_DaemonInfo *
 MHD_get_daemon_info (struct MHD_Daemon *daemon,
-                     enum MHD_DaemonInfoType infoType, ...)
+		     enum MHD_DaemonInfoType info_type, 
+		     ...)
 {
-  switch (infoType)
+  switch (info_type)
     {
     case MHD_DAEMON_INFO_KEY_SIZE:
       return NULL; /* no longer supported */
@@ -3750,19 +3779,20 @@ MHD_get_daemon_info (struct MHD_Daemon *daemon,
 
 
 /**
- * Sets the global error handler to a different implementation.  "cb"
+ * Sets the global error handler to a different implementation.  @a cb
  * will only be called in the case of typically fatal, serious
  * internal consistency issues.  These issues should only arise in the
  * case of serious memory corruption or similar problems with the
- * architecture.  While "cb" is allowed to return and MHD will then
+ * architecture.  While @a cb is allowed to return and MHD will then
  * try to continue, this is never safe.
  *
  * The default implementation that is used if no panic function is set
- * simply prints an error message and calls "abort".  Alternative
- * implementations might call "exit" or other similar functions.
+ * simply prints an error message and calls `abort()`.  Alternative
+ * implementations might call `exit()` or other similar functions.
  *
  * @param cb new error handler
- * @param cls passed to error handler
+ * @param cls passed to @a cb
+ * @ingroup logging
  */
 void 
 MHD_set_panic_func (MHD_PanicCallback cb, void *cls)
@@ -3775,7 +3805,8 @@ MHD_set_panic_func (MHD_PanicCallback cb, void *cls)
 /**
  * Obtain the version of this library
  *
- * @return static version string, e.g. "0.4.1"
+ * @return static version string, e.g. "0.9.9"
+ * @ingroup specialized
  */
 const char *
 MHD_get_version (void)

src/microhttpd/digestauth.c

@@ -348,6 +348,7 @@ check_nonce_nc (struct MHD_Connection *connection,
  * @param connection The MHD connection structure
  * @return NULL if no username could be found, a pointer
  * 			to the username if found
+ * @ingroup authentication
  */
 char *
 MHD_digest_auth_get_username(struct MHD_Connection *connection)
@@ -539,8 +540,9 @@ check_argument_match (struct MHD_Connection *connection,
  * @param password The password used in the authentication
  * @param nonce_timeout The amount of time for a nonce to be
  * 			invalid in seconds
- * @return MHD_YES if authenticated, MHD_NO if not,
- * 			MHD_INVALID_NONCE if nonce is invalid
+ * @return #MHD_YES if authenticated, #MHD_NO if not,
+ * 			#MHD_INVALID_NONCE if nonce is invalid
+ * @ingroup authentication
  */
 int
 MHD_digest_auth_check (struct MHD_Connection *connection,
@@ -739,9 +741,10 @@ MHD_digest_auth_check (struct MHD_Connection *connection,
  * @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
+ * @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
+ * @return #MHD_YES on success, #MHD_NO otherwise
+ * @ingroup authentication
  */
 int
 MHD_queue_auth_fail_response (struct MHD_Connection *connection,

src/microhttpd/postprocessor.c

@@ -244,10 +244,14 @@ struct MHD_PostProcessor
 
 
 /**
- * Create a PostProcessor.
+ * Create a `struct MHD_PostProcessor`.
  *
- * A PostProcessor can be used to (incrementally)
- * parse the data portion of a POST request.
+ * A `struct MHD_PostProcessor` can be used to (incrementally) parse
+ * the data portion of a POST request.  Note that some buggy browsers
+ * fail to set the encoding type.  If you want to support those, you
+ * may have to call #MHD_set_connection_value with the proper encoding
+ * type before creating a post processor (if no supported encoding
+ * type is set, this function will fail).
  *
  * @param connection the connection on which the POST is
  *        happening (used to determine the POST format)
@@ -255,11 +259,14 @@ struct MHD_PostProcessor
  *        internal buffering (used only for the parsing,
  *        specifically the parsing of the keys).  A
  *        tiny value (256-1024) should be sufficient.
- *        Do NOT use 0.
- * @param iter iterator to be called with the parsed data
- * @param iter_cls first argument to iter
+ *        Do NOT use a value smaller than 256.  For good
+ *        performance, use 32 or 64k (i.e. 65536).
+ * @param iter iterator to be called with the parsed data,
+ *        Must NOT be NULL.
+ * @param iter_cls first argument to @a iter
  * @return NULL on error (out of memory, unsupported encoding),
  *         otherwise a PP handle
+ * @ingroup request
  */
 struct MHD_PostProcessor *
 MHD_create_post_processor (struct MHD_Connection *connection,
@@ -1082,26 +1089,25 @@ END:
 
 
 /**
- * Parse and process POST data.
- * Call this function when POST data is available
- * (usually during an MHD_AccessHandlerCallback)
- * with the upload_data and upload_data_size.
- * Whenever possible, this will then cause calls
- * to the MHD_IncrementalKeyValueIterator.
+ * Parse and process POST data.  Call this function when POST data is
+ * available (usually during an #MHD_AccessHandlerCallback) with the
+ * "upload_data" and "upload_data_size".  Whenever possible, this will
+ * then cause calls to the #MHD_IncrementalKeyValueIterator.
  *
  * @param pp the post processor
- * @param post_data post_data_len bytes of POST data
- * @param post_data_len length of post_data
- * @return MHD_YES on success, MHD_NO on error
+ * @param post_data @a post_data_len bytes of POST data
+ * @param post_data_len length of @a post_data
+ * @return #MHD_YES on success, #MHD_NO on error
  *         (out-of-memory, iterator aborted, parse error)
+ * @ingroup request
  */
 int
 MHD_post_process (struct MHD_PostProcessor *pp,
                   const char *post_data, size_t post_data_len)
 {
-  if (post_data_len == 0)
+  if (0 == post_data_len)
     return MHD_YES;
-  if (pp == NULL)
+  if (NULL == pp)
     return MHD_NO;
   if (0 == strncasecmp (MHD_HTTP_POST_ENCODING_FORM_URLENCODED, pp->encoding,
                          strlen(MHD_HTTP_POST_ENCODING_FORM_URLENCODED)))
@@ -1119,10 +1125,11 @@ MHD_post_process (struct MHD_PostProcessor *pp,
  * Release PostProcessor resources.
  *
  * @param pp post processor context to destroy
- * @return MHD_YES if processing completed nicely,
- *         MHD_NO if there were spurious characters / formatting
+ * @return #MHD_YES if processing completed nicely,
+ *         #MHD_NO if there were spurious characters / formatting
  *                problems; it is common to ignore the return
  *                value of this function
+ * @ingroup request
  */
 int
 MHD_destroy_post_processor (struct MHD_PostProcessor *pp)

src/microhttpd/response.c

@@ -83,7 +83,8 @@ add_response_entry (struct MHD_Response *response,
  * @param response response to add a header to
  * @param header the header to add
  * @param content value to add
- * @return MHD_NO on error (i.e. invalid header or content format).
+ * @return #MHD_NO on error (i.e. invalid header or content format).
+ * @ingroup response
  */
 int
 MHD_add_response_header (struct MHD_Response *response,
@@ -102,7 +103,8 @@ MHD_add_response_header (struct MHD_Response *response,
  * @param response response to remove a header from
  * @param footer the footer to delete
  * @param content value to delete
- * @return MHD_NO on error (i.e. invalid footer or content format).
+ * @return #MHD_NO on error (i.e. invalid footer or content format).
+ * @ingroup response
  */
 int
 MHD_add_response_footer (struct MHD_Response *response,
@@ -116,16 +118,18 @@ MHD_add_response_footer (struct MHD_Response *response,
 
 
 /**
- * Delete a header line from the response.
+ * Delete a header (or footer) line from the response.
  *
  * @param response response to remove a header from
  * @param header the header to delete
  * @param content value to delete
- * @return MHD_NO on error (no such header known)
+ * @return #MHD_NO on error (no such header known)
+ * @ingroup response
  */
 int
 MHD_del_response_header (struct MHD_Response *response,
-                         const char *header, const char *content)
+                         const char *header,
+			 const char *content)
 {
   struct MHD_HTTP_Header *pos;
   struct MHD_HTTP_Header *prev;
@@ -156,13 +160,14 @@ MHD_del_response_header (struct MHD_Response *response,
 
 
 /**
- * Get all of the headers added to a response.
+ * Get all of the headers (and footers) 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
+ * @param iterator_cls extra argument to @a iterator
  * @return number of entries iterated over
+ * @ingroup response
  */
 int
 MHD_get_response_headers (struct MHD_Response *response,
@@ -184,11 +189,12 @@ MHD_get_response_headers (struct MHD_Response *response,
 
 
 /**
- * Get a particular header from the response.
+ * Get a particular header (or footer) from the response.
  *
  * @param response response to query
  * @param key which header to get
  * @return NULL if header does not exist
+ * @ingroup response
  */
 const char *
 MHD_get_response_header (struct MHD_Response *response, 
@@ -209,16 +215,17 @@ MHD_get_response_header (struct MHD_Response *response,
  * Create a response object.  The response object can be extended with
  * header information and then be used any number of times.
  *
- * @param size size of the data portion of the response, MHD_SIZE_UNKNOWN for unknown
+ * @param size size of the data portion of the response, #MHD_SIZE_UNKNOWN for unknown
  * @param block_size preferred block size for querying crc (advisory only,
- *                   MHD may still call crc using smaller chunks); this
+ *                   MHD may still call @a crc using smaller chunks); this
  *                   is essentially the buffer size used for IO, clients
  *                   should pick a value that is appropriate for IO and
  *                   memory performance requirements
  * @param crc callback to use to obtain response data
- * @param crc_cls extra argument to crc
- * @param crfc callback to call to free crc_cls resources
+ * @param crc_cls extra argument to @a crc
+ * @param crfc callback to call to free @a crc_cls resources
  * @return NULL on error (i.e. invalid arguments, out of memory)
+ * @ingroup response
  */
 struct MHD_Response *
 MHD_create_response_from_callback (uint64_t size,
@@ -298,13 +305,21 @@ free_callback (void *cls)
  * header information and then be used any number of times.
  *
  * @param size size of the data portion of the response
- * @param fd file descriptor referring to a file on disk with the data
- * @param offset offset to start reading from in the file
+ * @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 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
+ *        the MHD manual for more details.
  * @return NULL on error (i.e. invalid arguments, out of memory)
+ * @ingroup response
  */
-struct MHD_Response *MHD_create_response_from_fd_at_offset (size_t size,
-							    int fd,
-							    off_t offset)
+struct MHD_Response *
+MHD_create_response_from_fd_at_offset (size_t size,
+				       int fd,
+				       off_t offset)
 {
   struct MHD_Response *response;
 
@@ -329,9 +344,11 @@ struct MHD_Response *MHD_create_response_from_fd_at_offset (size_t size,
  * @param size size of the data portion of the response
  * @param fd file descriptor referring to a file on disk with the data
  * @return NULL on error (i.e. invalid arguments, out of memory)
+ * @ingroup response
  */
-struct MHD_Response *MHD_create_response_from_fd (size_t size,
-						  int fd)
+struct MHD_Response *
+MHD_create_response_from_fd (size_t size,
+			     int fd)
 {
   return MHD_create_response_from_fd_at_offset (size, fd, 0);
 }
@@ -341,14 +358,15 @@ struct MHD_Response *MHD_create_response_from_fd (size_t size,
  * Create a response object.  The response object can be extended with
  * header information and then be used any number of times.
  *
- * @param size size of the data portion of the response
+ * @param size size of the @a data portion of the response
  * @param data the data itself
  * @param must_free libmicrohttpd should free data when done
- * @param must_copy libmicrohttpd must make a copy of data
+ * @param must_copy libmicrohttpd must make a copy of @a data
  *        right away, the data maybe released anytime after
  *        this call returns
  * @return NULL on error (i.e. invalid arguments, out of memory)
- * @deprecated use MHD_create_response_from_buffer instead
+ * @deprecated use #MHD_create_response_from_buffer instead
+ * @ingroup response
  */
 struct MHD_Response *
 MHD_create_response_from_data (size_t size,
@@ -399,6 +417,7 @@ MHD_create_response_from_data (size_t size,
  * @param buffer size bytes containing the response's data portion
  * @param mode flags for buffer management
  * @return NULL on error (i.e. invalid arguments, out of memory)
+ * @ingroup response
  */
 struct MHD_Response *
 MHD_create_response_from_buffer (size_t size,
@@ -417,6 +436,9 @@ MHD_create_response_from_buffer (size_t size,
  * libmicrohttpd may keep some of the resources around if the response
  * is still in the queue for some clients, so the memory may not
  * necessarily be freed immediatley.
+ *
+ * @param response response to destroy
+ * @ingroup response
  */
 void
 MHD_destroy_response (struct MHD_Response *response)