Fix comment format in http.h

Functions decl must follow comment to be correctly documented

PUBLISHED_FROM=6ab035cda470c2c23240db4435abd8c241c71b0d

docs/c-api/http.h/items.json

@@ -16,6 +16,14 @@
             "type": "markdown",
             "name": "mg_send_websocket_handshake2.md"
         },
+        {
+            "type": "markdown",
+            "name": "mg_connect_ws.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_connect_ws_opt.md"
+        },
         {
             "type": "markdown",
             "name": "mg_send_websocket_frame.md"
@@ -76,10 +84,30 @@
             "type": "markdown",
             "name": "mg_http_create_digest_auth_header.md"
         },
+        {
+            "type": "markdown",
+            "name": "mg_connect_http.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_connect_http_opt.md"
+        },
         {
             "type": "markdown",
             "name": "mg_serve_http.md"
         },
+        {
+            "type": "markdown",
+            "name": "mg_register_http_endpoint.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_file_upload_handler.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_fu_fname_fn.md"
+        },
         {
             "type": "markdown",
             "name": "struct_http_message.md"

docs/c-api/http.h/mg_connect_http.md

@@ -0,0 +1,35 @@
+---
+title: "mg_connect_http()"
+decl_name: "mg_connect_http"
+symbol_kind: "func"
+signature: |
+  struct mg_connection *mg_connect_http(struct mg_mgr *mgr,
+                                        mg_event_handler_t event_handler,
+                                        const char *url,
+                                        const char *extra_headers,
+                                        const char *post_data);
+---
+
+Helper function that creates outbound HTTP connection.
+
+`url` is a URL to fetch. It must be properly URL-encoded, e.g. have
+no spaces, etc. By default, `mg_connect_http()` sends Connection and
+Host headers. `extra_headers` is an extra HTTP headers to send, e.g.
+`"User-Agent: my-app\r\n"`.
+If `post_data` is NULL, then GET request is created. Otherwise, POST request
+is created with the specified POST data. Note that if the data being posted
+is a form submission, the `Content-Type` header should be set accordingly
+(see example below).
+
+Examples:
+
+```c
+  nc1 = mg_connect_http(mgr, ev_handler_1, "http://www.google.com", NULL,
+                        NULL);
+  nc2 = mg_connect_http(mgr, ev_handler_1, "https://github.com", NULL, NULL);
+  nc3 = mg_connect_http(
+      mgr, ev_handler_1, "my_server:8000/form_submit/",
+      "Content-Type: application/x-www-form-urlencoded\r\n",
+      "var_1=value_1&var_2=value_2");
+``` 
+

docs/c-api/http.h/mg_connect_http_opt.md

@@ -0,0 +1,18 @@
+---
+title: "mg_connect_http_opt()"
+decl_name: "mg_connect_http_opt"
+symbol_kind: "func"
+signature: |
+  struct mg_connection *mg_connect_http_opt(struct mg_mgr *mgr,
+                                            mg_event_handler_t ev_handler,
+                                            struct mg_connect_opts opts,
+                                            const char *url,
+                                            const char *extra_headers,
+                                            const char *post_data);
+---
+
+Helper function that creates outbound HTTP connection.
+
+Mostly identical to mg_connect_http, but allows to provide extra parameters
+(for example, SSL parameters 
+

docs/c-api/http.h/mg_connect_ws.md

@@ -0,0 +1,30 @@
+---
+title: "mg_connect_ws()"
+decl_name: "mg_connect_ws"
+symbol_kind: "func"
+signature: |
+  struct mg_connection *mg_connect_ws(struct mg_mgr *mgr,
+                                      mg_event_handler_t event_handler,
+                                      const char *url, const char *protocol,
+                                      const char *extra_headers);
+---
+
+Helper function that creates an outbound WebSocket connection.
+
+`url` is a URL to connect to. It must be properly URL-encoded, e.g. have
+no spaces, etc. By default, `mg_connect_ws()` sends Connection and
+Host headers. `extra_headers` is an extra HTTP headers to send, e.g.
+`"User-Agent: my-app\r\n"`.
+If `protocol` is not NULL, then a `Sec-WebSocket-Protocol` header is sent.
+
+Examples:
+
+```c
+  nc1 = mg_connect_ws(mgr, ev_handler_1, "ws://echo.websocket.org", NULL,
+                      NULL);
+  nc2 = mg_connect_ws(mgr, ev_handler_1, "wss://echo.websocket.org", NULL,
+                      NULL);
+  nc3 = mg_connect_ws(mgr, ev_handler_1, "ws://api.cesanta.com",
+                      "clubby.cesanta.com", NULL);
+``` 
+

docs/c-api/http.h/mg_connect_ws_opt.md

@@ -0,0 +1,17 @@
+---
+title: "mg_connect_ws_opt()"
+decl_name: "mg_connect_ws_opt"
+symbol_kind: "func"
+signature: |
+  struct mg_connection *mg_connect_ws_opt(struct mg_mgr *mgr,
+                                          mg_event_handler_t ev_handler,
+                                          struct mg_connect_opts opts,
+                                          const char *url, const char *protocol,
+                                          const char *extra_headers);
+---
+
+Helper function that creates an outbound WebSocket connection
+
+Mostly identical to mg_connect_ws, but allows to provide extra parameters
+(for example, SSL parameters 
+

docs/c-api/http.h/mg_file_upload_handler.md

@@ -0,0 +1,39 @@
+---
+title: "mg_file_upload_handler()"
+decl_name: "mg_file_upload_handler"
+symbol_kind: "func"
+signature: |
+  void mg_file_upload_handler(struct mg_connection *nc, int ev, void *ev_data,
+                              mg_fu_fname_fn local_name_fn);
+---
+
+File upload handler.
+This handler can be used to implement file uploads with minimum code.
+This handler will process MG_EV_HTTP_PART_* events and store file data into
+a local file.
+`local_name_fn` will be invoked with whatever name was provided by the client
+and will expect the name of the local file to open. Return value of NULL will
+abort file upload (client will get a "403 Forbidden" response). If non-null,
+the returned string must be heap-allocated and will be freed by the caller.
+Exception: it is ok to return the same string verbatim.
+
+Example:
+
+```c
+struct mg_str upload_fname(struct mg_connection *nc, struct mg_str fname) {
+  // Just return the same filename. Do not actually do this except in test!
+  // fname is user-controlled and needs to be sanitized.
+  return fname;
+}
+void ev_handler(struct mg_connection *nc, int ev, void *ev_data) {
+  switch (ev) {
+    ...
+    case MG_EV_HTTP_PART_BEGIN:
+    case MG_EV_HTTP_PART_DATA:
+    case MG_EV_HTTP_PART_END:
+      mg_file_upload_handler(nc, ev, ev_data, upload_fname);
+      break;
+  }
+}
+``` 
+

docs/c-api/http.h/mg_fu_fname_fn.md

@@ -0,0 +1,11 @@
+---
+title: "mg_fu_fname_fn"
+decl_name: "mg_fu_fname_fn"
+symbol_kind: "typedef"
+signature: |
+  typedef struct mg_str (*mg_fu_fname_fn)(struct mg_connection *nc,
+                                          struct mg_str fname);
+---
+
+Callback prototype for `mg_file_upload_handler()`. 
+

docs/c-api/http.h/mg_register_http_endpoint.md

@@ -0,0 +1,35 @@
+---
+title: "mg_register_http_endpoint()"
+decl_name: "mg_register_http_endpoint"
+symbol_kind: "func"
+signature: |
+  void mg_register_http_endpoint(struct mg_connection *nc, const char *uri_path,
+                                 mg_event_handler_t handler);
+---
+
+Register callback for specified http endpoint
+Note: if callback is registered it is called instead of
+callback provided in mg_bind
+
+Example code snippet:
+
+```c
+static void handle_hello1(struct mg_connection *nc, int ev, void *ev_data) {
+  (void) ev; (void) ev_data;
+  mg_printf(nc, "HTTP/1.0 200 OK\r\n\r\n[I am Hello1]");
+ nc->flags |= MG_F_SEND_AND_CLOSE;
+}
+
+static void handle_hello1(struct mg_connection *nc, int ev, void *ev_data) {
+ (void) ev; (void) ev_data;
+  mg_printf(nc, "HTTP/1.0 200 OK\r\n\r\n[I am Hello2]");
+ nc->flags |= MG_F_SEND_AND_CLOSE;
+}
+
+void init() {
+  nc = mg_bind(&mgr, local_addr, cb1);
+  mg_register_http_endpoint(nc, "/hello1", handle_hello1);
+  mg_register_http_endpoint(nc, "/hello1/hello2", handle_hello2);
+}
+``` 
+

mongoose.h

@@ -2208,7 +2208,6 @@ void mg_send_websocket_handshake2(struct mg_connection *nc, const char *path,
  *                       "clubby.cesanta.com", NULL);
  * ```
  */
-
 struct mg_connection *mg_connect_ws(struct mg_mgr *mgr,
                                     mg_event_handler_t event_handler,
                                     const char *url, const char *protocol,
@@ -2220,7 +2219,6 @@ struct mg_connection *mg_connect_ws(struct mg_mgr *mgr,
  * Mostly identical to mg_connect_ws, but allows to provide extra parameters
  * (for example, SSL parameters
  */
-
 struct mg_connection *mg_connect_ws_opt(struct mg_mgr *mgr,
                                         mg_event_handler_t ev_handler,
                                         struct mg_connect_opts opts,
@@ -2456,6 +2454,7 @@ int mg_http_create_digest_auth_header(char *buf, size_t buf_len,
                                       const char *method, const char *uri,
                                       const char *auth_domain, const char *user,
                                       const char *passwd);
+
 /*
  * Helper function that creates outbound HTTP connection.
  *
@@ -2480,7 +2479,6 @@ int mg_http_create_digest_auth_header(char *buf, size_t buf_len,
  *       "var_1=value_1&var_2=value_2");
  * ```
  */
-
 struct mg_connection *mg_connect_http(struct mg_mgr *mgr,
                                       mg_event_handler_t event_handler,
                                       const char *url,
@@ -2493,7 +2491,6 @@ struct mg_connection *mg_connect_http(struct mg_mgr *mgr,
  * Mostly identical to mg_connect_http, but allows to provide extra parameters
  * (for example, SSL parameters
  */
-
 struct mg_connection *mg_connect_http_opt(struct mg_mgr *mgr,
                                           mg_event_handler_t ev_handler,
                                           struct mg_connect_opts opts,
@@ -2649,11 +2646,15 @@ void mg_serve_http(struct mg_connection *nc, struct http_message *hm,
  * }
  * ```
  */
-
 void mg_register_http_endpoint(struct mg_connection *nc, const char *uri_path,
                                mg_event_handler_t handler);
 
 #ifdef MG_ENABLE_HTTP_STREAMING_MULTIPART
+
+/* Callback prototype for `mg_file_upload_handler()`. */
+typedef struct mg_str (*mg_fu_fname_fn)(struct mg_connection *nc,
+                                        struct mg_str fname);
+
 /*
  * File upload handler.
  * This handler can be used to implement file uploads with minimum code.
@@ -2685,9 +2686,6 @@ void mg_register_http_endpoint(struct mg_connection *nc, const char *uri_path,
  * }
  * ```
  */
-
-typedef struct mg_str (*mg_fu_fname_fn)(struct mg_connection *nc,
-                                        struct mg_str fname);
 void mg_file_upload_handler(struct mg_connection *nc, int ev, void *ev_data,
                             mg_fu_fname_fn local_name_fn);
 #endif /* MG_ENABLE_HTTP_STREAMING_MULTIPART */