https: improve documentation

doc/Doxyfile.in

@@ -759,7 +759,8 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = @top_srcdir@/src \
-                         @top_srcdir@/include
+                         @top_srcdir@/include \
+                         @top_srcdir@/modules/access/http
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

modules/access/http/conn.h

@@ -18,6 +18,13 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
+/**
+ * \defgroup http_conn Connections
+ * HTTP connections
+ * \ingroup http_connmgr
+ * @{
+ */
+
 struct vlc_tls;
 struct vlc_http_conn;
 struct vlc_http_msg;
@@ -47,8 +54,22 @@ static inline void vlc_http_conn_release(struct vlc_http_conn *conn)
     conn->cbs->release(conn);
 }
 
+/**
+ * \defgroup http1 HTTP/1.x
+ * @{
+ */
 struct vlc_http_conn *vlc_h1_conn_create(struct vlc_tls *, bool proxy);
-struct vlc_http_conn *vlc_h2_conn_create(struct vlc_tls *);
-
 struct vlc_http_stream *vlc_chunked_open(struct vlc_http_stream *,
                                          struct vlc_tls *);
+
+/** @} */
+
+/**
+ * \defgroup h2 HTTP/2.0
+ * @{
+ */
+struct vlc_http_conn *vlc_h2_conn_create(struct vlc_tls *);
+
+/** @} */
+
+/** @} */

modules/access/http/connmgr.h

@@ -18,19 +18,63 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
+/**
+ * \defgroup http HTTP
+ * Hyper-Text Transfer Protocol
+ * \defgroup http_connmgr Connection manager
+ * HTTP connection management
+ * \ingroup http
+ * @{
+ * \file connmgr.h
+ */
+
 struct vlc_http_mgr;
 struct vlc_http_msg;
 struct vlc_http_cookie_jar_t;
 
+/**
+ * Sends an HTTP request
+ *
+ * Sends an HTTP request, by either reusing an existing HTTP connection or
+ * establishing a new one. If succesful, the initial HTTP response header is
+ * returned.
+ *
+ * @param mgr HTTP connection manager
+ * @param https whether to use HTTPS (true) or unencrypted HTTP (false)
+ * @param host name of authoritative HTTP server to send the request to
+ * @param port TCP server port number, or 0 for the default port number
+ * @param req HTTP request header to send
+ *
+ * @return The initial HTTP response header, or NULL in case of failure.
+ */
 struct vlc_http_msg *vlc_http_mgr_request(struct vlc_http_mgr *mgr, bool https,
                                           const char *host, unsigned port,
                                           const struct vlc_http_msg *req);
+
 int vlc_http_mgr_send_cookies(struct vlc_http_mgr *, struct vlc_http_msg *);
 void vlc_http_mgr_recv_cookies(struct vlc_http_mgr *mgr, bool https,
                                const char *host, const char *path,
                                const struct vlc_http_msg *resp);
 
+/**
+ * Creates an HTTP connection manager
+ *
+ * Allocates an HTTP client connections manager.
+ *
+ * @param obj parent VLC object
+ * @param jar HTTP cookies jar (NULL to disable cookies)
+ * @param h2c Favor unencrypted HTTP/2 over HTTP/1.1
+ */
 struct vlc_http_mgr *vlc_http_mgr_create(vlc_object_t *obj,
                                          struct vlc_http_cookie_jar_t *jar,
                                          bool h2c);
+
+/**
+ * Destroys an HTTP connection manager
+ *
+ * Deallocates an HTTP client connections manager created by
+ * vlc_http_msg_destroy(). Any remaining connection is closed and destroyed.
+ */
 void vlc_http_mgr_destroy(struct vlc_http_mgr *mgr);
+
+/** @} */

modules/access/http/file.h

@@ -20,20 +20,85 @@
 
 #include <stdint.h>
 
+/**
+ * \defgroup http_file Files
+ * HTTP read-only files
+ * \ingroup http_res
+ * @{
+ */
+
 struct vlc_http_file;
 struct vlc_http_mgr;
 struct block_t;
 
+/**
+ * Creates an HTTP file.
+ *
+ * Allocates a structure for a remote HTTP-served read-only file.
+ *
+ * @param url URL of the file to read
+ * @param ua user agent string (or NULL to ignore)
+ * @param ref referral URL (or NULL to ignore)
+ */
 struct vlc_http_file *vlc_http_file_create(struct vlc_http_mgr *mgr,
                                            const char *url, const char *ua,
                                            const char *ref);
-void vlc_http_file_destroy(struct vlc_http_file *file);
 
-int vlc_http_file_get_status(struct vlc_http_file *file);
-char *vlc_http_file_get_redirect(struct vlc_http_file *file);
+/**
+ * Destroys an HTTP file.
+ *
+ * Releases all resources allocated or held by the HTTP file object.
+ */
+void vlc_http_file_destroy(struct vlc_http_file *);
+
+int vlc_http_file_get_status(struct vlc_http_file *);
+
+/**
+ * Gets redirection URL.
+ *
+ * Checks if the file URL lead to a redirection. If so, return the redirect
+ * location.
+ *
+ * @return Heap-allocated URL or NULL if no redirection.
+ */
+char *vlc_http_file_get_redirect(struct vlc_http_file *);
+
+/**
+ * Gets file size.
+ *
+ * Determines the file size in bytes.
+ *
+ * @return Bytes count or (uintmax_t)-1 if unknown.
+ */
+uintmax_t vlc_http_file_get_size(struct vlc_http_file *);
+
+/**
+ * Checks seeking support.
+ *
+ * @retval true if file supports seeking
+ * @retval false if file does not support seeking
+ */
+bool vlc_http_file_can_seek(struct vlc_http_file *);
+
+/**
+ * Gets MIME type.
+ *
+ * @return Heap-allocated MIME type string, or NULL if unknown.
+ */
+char *vlc_http_file_get_type(struct vlc_http_file *);
+
+/**
+ * Sets the read offset.
+ *
+ * @param offset byte offset of next read
+ * @retval 0 if seek succeeded
+ * @retval -1 if seek failed
+ */
+int vlc_http_file_seek(struct vlc_http_file *, uintmax_t offset);
+
+/**
+ * Reads data.
+ */
+struct block_t *vlc_http_file_read(struct vlc_http_file *);
 
-uintmax_t vlc_http_file_get_size(struct vlc_http_file *file);
-bool vlc_http_file_can_seek(struct vlc_http_file *file);
-char *vlc_http_file_get_type(struct vlc_http_file *file);
-int vlc_http_file_seek(struct vlc_http_file *file, uintmax_t offset);
-struct block_t *vlc_http_file_read(struct vlc_http_file *file);
+/** @} */

modules/access/http/h2frame.h

@@ -21,6 +21,12 @@
 #include <stdbool.h>
 #include <stdint.h>
 
+/**
+ * \defgroup h2_frames HTTP/2 frames
+ * \ingroup h2
+ * @{
+ */
+
 struct vlc_h2_frame
 {
     struct vlc_h2_frame *next;
@@ -128,3 +134,5 @@ const uint8_t *vlc_h2_frame_data_get(const struct vlc_h2_frame *f,
         const struct vlc_h2_frame *: (vlc_h2_frame_data_get)(f, l), \
         struct vlc_h2_frame *: (uint8_t *)(vlc_h2_frame_data_get)(f, l))
 #endif
+
+/** @} */

modules/access/http/h2output.h

@@ -18,6 +18,12 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
+/**
+ * \defgroup h2_output HTTP/2 output
+ * \ingroup h2
+ * @{
+ */
+
 struct vlc_h2_output;
 struct vlc_h2_frame;
 struct vlc_tls;
@@ -27,3 +33,5 @@ int vlc_h2_output_send(struct vlc_h2_output *, struct vlc_h2_frame *);
 
 struct vlc_h2_output *vlc_h2_output_create(struct vlc_tls *, bool client);
 void vlc_h2_output_destroy(struct vlc_h2_output *);
+
+/** @} */

modules/access/http/hpack.h

@@ -18,6 +18,13 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
+/**
+ * \defgroup hpack HPACK compression
+ * HTTP/2 header compression (HPACK)
+ * \ingroup h2
+ * @{
+ */
+
 struct hpack_decoder;
 
 struct hpack_decoder *hpack_decode_init(size_t header_table_size);
@@ -30,3 +37,5 @@ size_t hpack_encode_hdr_neverindex(uint8_t *restrict buf, size_t size,
                                    const char *name, const char *value);
 size_t hpack_encode(uint8_t *restrict buf, size_t size,
                     const char *const headers[][2], unsigned count);
+
+/** @} */

modules/access/http/live.h

@@ -18,6 +18,13 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
+/**
+ * \defgroup http_live Live streams
+ * Trivial HTTP-based live streams
+ * \ingroup http_res
+ * @{
+ */
+
 struct vlc_http_live;
 struct block_t;
 
@@ -30,3 +37,5 @@ int vlc_http_live_get_status(struct vlc_http_live *live);
 char *vlc_http_live_get_redirect(struct vlc_http_live *live);
 char *vlc_http_live_get_type(struct vlc_http_live *live);
 block_t *vlc_http_live_read(struct vlc_http_live *live);
+
+/** @} */

modules/access/http/resource.h

@@ -18,6 +18,13 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
+/**
+ * \defgroup http_res Resources
+ * Remote HTTP resources identified by a URL
+ * \ingroup http
+ * @{
+ */
+
 struct vlc_http_msg;
 struct vlc_http_mgr;
 
@@ -44,3 +51,5 @@ char *vlc_http_res_get_redirect(const struct vlc_http_resource *,
                                 const struct vlc_http_msg *resp);
 char *vlc_http_res_get_type(const struct vlc_http_msg *resp);
 struct block_t *vlc_http_res_read(struct vlc_http_msg *resp);
+
+/** @} */