[libmicrohttpd] 02/05: MHD_create_response_*() functions: improved doxy

[gnunet]

This is an automated email from the git hooks/post-receive script.

karlson2k pushed a commit to branch master
in repository libmicrohttpd.

commit 3bd79348f0be80753094a52316c0101949a032d7
Author: Evgeny Grin (Karlson2k) <k2k@narod.ru>
AuthorDate: Sun Jun 13 13:41:29 2021 +0300

    MHD_create_response_*() functions: improved doxy
    
    * Clearer description of how buffer/FD/ other is used
    * Sync .c/.h doxy
    * Clarification for HEAD requests answering
---
 src/include/microhttpd.h  | 101 ++++++++++++++++++++++++++++++++---------
 src/microhttpd/response.c | 112 +++++++++++++++++++++++++++++++++++++---------
 2 files changed, 171 insertions(+), 42 deletions(-)

diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
index 4c9937bf..0fee465c 100644
--- a/src/include/microhttpd.h
+++ b/src/include/microhttpd.h
@@ -3208,8 +3208,15 @@ enum MHD_ResponseMemoryMode
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided buffer used as
+ * the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response
  * @param buffer size bytes containing the response's data portion
@@ -3224,8 +3231,15 @@ MHD_create_response_from_buffer (size_t size,
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided buffer used as
+ * the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response
  * @param buffer size bytes containing the response's data portion
@@ -3242,9 +3256,15 @@ MHD_create_response_from_buffer_with_free_callback 
(size_t size,
 
 
 /**
- * Create a response object.
- * The response object can be extended with header information and then be
- * used any number of times.
+ * Create a response object with the content of provided buffer used as
+ * the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response
  * @param buffer size bytes containing the response's data portion
@@ -3264,8 +3284,15 @@ MHD_create_response_from_buffer_with_free_callback_cls 
(size_t size,
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided file used as
+ * the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response
  * @param fd file descriptor referring to a file on disk with the
@@ -3280,8 +3307,15 @@ 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 ONLY ONCE.
+ * Create a response object with the response body created by reading
+ * the provided pipe.
+ *
+ * The response object can be extended with header information and
+ * then be used ONLY ONCE.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param fd file descriptor referring to a read-end of a pipe with the
  *        data; will be closed when response is destroyed;
@@ -3295,8 +3329,15 @@ MHD_create_response_from_pipe (int fd);
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided file used as
+ * the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response;
  *        sizes larger than 2 GiB may be not supported by OS or
@@ -3313,8 +3354,15 @@ MHD_create_response_from_fd64 (uint64_t size,
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided file with
+ * specified offset used as the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response
  * @param fd file descriptor referring to a file on disk with the
@@ -3346,8 +3394,15 @@ MHD_create_response_from_fd_at_offset (size_t size,
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided file with
+ * specified offset used as the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response;
  *        sizes larger than 2 GiB may be not supported by OS or
@@ -3368,9 +3423,15 @@ MHD_create_response_from_fd_at_offset64 (uint64_t size,
 
 
 /**
- * Create a response object from an array of memory buffers.
- * The response object can be extended with header information and then be used
- * any number of times.
+ * Create a response object with an array of memory buffers
+ * used as the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param iov the array for response data buffers, an internal copy of this
  *        will be made
diff --git a/src/microhttpd/response.c b/src/microhttpd/response.c
index eb29ab64..3c8444ce 100644
--- a/src/microhttpd/response.c
+++ b/src/microhttpd/response.c
@@ -588,8 +588,15 @@ free_callback (void *cls)
 #undef MHD_create_response_from_fd_at_offset
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided file with
+ * specified offset used as the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response
  * @param fd file descriptor referring to a file on disk with the
@@ -615,8 +622,15 @@ MHD_create_response_from_fd_at_offset (size_t size,
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided file with
+ * specified offset used as the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response;
  *        sizes larger than 2 GiB may be not supported by OS or
@@ -665,8 +679,15 @@ MHD_create_response_from_fd_at_offset64 (uint64_t size,
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used ONLY ONCE.
+ * Create a response object with the response body created by reading
+ * the provided pipe.
+ *
+ * The response object can be extended with header information and
+ * then be used ONLY ONCE.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param fd file descriptor referring to a read-end of a pipe with the
  *        data; will be closed when response is destroyed;
@@ -694,8 +715,15 @@ MHD_create_response_from_pipe (int fd)
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided file used as
+ * the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response
  * @param fd file descriptor referring to a file on disk with the data
@@ -713,8 +741,15 @@ 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.
+ * Create a response object with the content of provided file used as
+ * the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response;
  *        sizes larger than 2 GiB may be not supported by OS or
@@ -736,8 +771,15 @@ MHD_create_response_from_fd64 (uint64_t size,
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided buffer used as
+ * the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the @a data portion of the response
  * @param data the data itself
@@ -800,8 +842,15 @@ MHD_create_response_from_data (size_t size,
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided buffer used as
+ * the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response
  * @param buffer size bytes containing the response's data portion
@@ -822,8 +871,15 @@ MHD_create_response_from_buffer (size_t size,
 
 
 /**
- * Create a response object.  The response object can be extended with
- * header information and then be used any number of times.
+ * Create a response object with the content of provided buffer used as
+ * the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response
  * @param buffer size bytes containing the response's data portion
@@ -851,9 +907,15 @@ MHD_create_response_from_buffer_with_free_callback (size_t 
size,
 
 
 /**
- * Create a response object.
- * The response object can be extended with header information and then be
- * used any number of times.
+ * Create a response object with the content of provided buffer used as
+ * the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param size size of the data portion of the response
  * @param buffer size bytes containing the response's data portion
@@ -883,9 +945,15 @@ MHD_create_response_from_buffer_with_free_callback_cls 
(size_t size,
 
 
 /**
- * Create a response object from an array of memory buffers.
- * The response object can be extended with header information and then be used
- * any number of times.
+ * Create a response object with an array of memory buffers
+ * used as the response body.
+ *
+ * The response object can be extended with header information and then
+ * be used any number of times.
+ *
+ * If response object is used to answer HEAD request then the body
+ * of the response is not used, while all headers (including automatic
+ * headers) are used.
  *
  * @param iov the array for response data buffers, an internal copy of this
  *        will be made

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.