Docs are generated for Mongoose

Comments in headers are changed a bit: removed adoc-specific stuff,
markdown is used instead

PUBLISHED_FROM=9242cce85cc52a47a197d377e7e23804721a6bb5

docs/build-options/disabling-flags.md

+---
+title: Disabling flags
+---
+
+- `MG_DISABLE_HTTP_WEBSOCKET` disable HTTP + Websocket protocol support
+- `MG_DISABLE_HTTP_DIGEST_AUTH` disable HTTP Digest (MD5) authorization support
+- `MG_DISABLE_MQTT` disable MQTT support
+- `MG_DISABLE_SHA1` disable SHA1 support (used by Websocket)
+- `MG_DISABLE_MD5` disable MD5 support (used by HTTP auth)
+- `MG_DISABLE_JSON_RPC` disable JSON-RPC support
+- `MG_DISABLE_SOCKETPAIR` disable `mg_broadcast()` API
+- `MG_DISABLE_HTTP_KEEP_ALIVE` useful for embedded systems to save resources

docs/build-options/enabling-flags.md

+---
+title: Enabling flags
+---
+
+- `MG_ENABLE_SSL` Enable OpenSSL support
+- `MG_ENABLE_IPV6` Enable IPV6 support
+- `MG_ENABLE_THREADS` enable `mg_start_thread()` API
+- `MG_ENABLE_MQTT_BROKER` enable MQTT broker
+- `MG_ENABLE_DNS_SERVER` enable DNS server
+- `MG_ENABLE_COAP` enable CoAP protocol
+- `MG_ENABLE_GETADDRINFO` enable `getaddrinfo()` in `mg_resolve2()`

docs/build-options/intro.md

+---
+title: Build Options
+---
+
+Mongoose source code ships in a single .c file that contains functionality
+for all supported protocols (modules). Modules can be disabled at compile
+time which reduces executable size. That can be done by setting preprocessor
+flags. Also, some preprocessor flags can be used to tune internal Mongoose
+parameters.
+
+To set a preprocessor flag during compile time, use `-D <PREPROCESSOR_FLAG>`
+compiler option. For example, to disable both MQTT and JSON-RPC,
+compile the application `my_app.c` like this (assumed UNIX system):
+
+```
+  $ cc my_app.c mongoose.c -D MG_DISABLE_MQTT -D MG_DISABLE_JSON_RPC
+```

docs/build-options/items.json

+{
+  "items": [
+    { "type": "markdown", "name": "intro.md" },
+    { "type": "markdown", "name": "enabling-flags.md" },
+    { "type": "markdown", "name": "disabling-flags.md" },
+    { "type": "markdown", "name": "platform-spec.md" },
+    { "type": "markdown", "name": "tunables.md" }
+  ]
+}

docs/build-options/platform-spec.md

+---
+title: Platform specific
+---
+
+Mongoose tries to detect the target platform whenever possible, but in some cases you have
+to explicitly declare some peculiarities of your target, such as:
+
+- `MG_LWIP`: use LWIP networking stack
+- `MG_CC3200`: enable workarounds for the TI CC3200 target.
+- `MG_ESP8266`: enable workarounds for the ESP8266 target, add `RTOS_SDK` to specify the RTOS SDK flavour.

docs/build-options/tunables.md

+---
+title: Tunables
+---
+
+- `MG_MALLOC`, `MG_CALLOC`, `MG_REALLOC`, `MG_FREE` allow to use custom
+  memory allocator, e.g. `-DMG_MALLOC=my_malloc`
+- `MG_USE_READ_WRITE` when set replaces calls to `recv` with `read` and `send` with `write`,
+  thus enabling to add any kind of file descriptor (files, serial devices) to an event manager.
+- `MG_SSL_CRYPTO_MODERN`, `MG_SSL_CRYPTO_OLD` - choose either "Modern" or "Old" ciphers
+  instead of the default "Intermediate" setting.
+  See [this article](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_configurations) for details.

docs/c-api/coap.h/intro.md

+---
+title: "CoAP"
+symbol_kind: "intro"
+decl_name: "coap.h"
+---
+
+CoAP message format:
+
+```
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
+|Ver| T | TKL | Code | Message ID | Token (if any, TKL bytes) ...
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
+| Options (if any) ...            |1 1 1 1 1 1 1 1| Payload (if any) ...
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
+```
+

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

+{
+    "items": [
+        {
+            "type": "markdown",
+            "name": "intro.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_set_protocol_coap.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_coap_add_option.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_coap_free_options.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_coap_send_message.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_coap_send_ack.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_coap_parse.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_coap_compose.md"
+        },
+        {
+            "type": "markdown",
+            "name": "struct_mg_coap_option.md"
+        },
+        {
+            "type": "markdown",
+            "name": "struct_mg_coap_message.md"
+        }
+    ]
+}

docs/c-api/coap.h/mg_coap_add_option.md

+---
+title: "mg_coap_add_option()"
+decl_name: "mg_coap_add_option"
+symbol_kind: "func"
+signature: |
+  struct mg_coap_option *mg_coap_add_option(struct mg_coap_message *cm,
+                                            uint32_t number, char *value,
+                                            size_t len);
+---
+
+Add new option to mg_coap_message structure.
+Returns pointer to the newly created option. 
+

docs/c-api/coap.h/mg_coap_compose.md

+---
+title: "mg_coap_compose()"
+decl_name: "mg_coap_compose"
+symbol_kind: "func"
+signature: |
+  uint32_t mg_coap_compose(struct mg_coap_message *cm, struct mbuf *io);
+---
+
+Composes CoAP message from mg_coap_message structure.
+This is a helper function.
+Return value: see `mg_coap_send_message()` 
+

docs/c-api/coap.h/mg_coap_free_options.md

+---
+title: "mg_coap_free_options()"
+decl_name: "mg_coap_free_options"
+symbol_kind: "func"
+signature: |
+  void mg_coap_free_options(struct mg_coap_message *cm);
+---
+
+Free the memory allocated for options,
+if cm paramater doesn't contain any option does nothing. 
+

docs/c-api/coap.h/mg_coap_parse.md

+---
+title: "mg_coap_parse()"
+decl_name: "mg_coap_parse"
+symbol_kind: "func"
+signature: |
+  uint32_t mg_coap_parse(struct mbuf *io, struct mg_coap_message *cm);
+---
+
+Parse COAP message and fills mg_coap_message and returns cm->flags.
+This is a helper function.
+
+NOTE: usually CoAP work over UDP, so lack of data means format error,
+but in theory it is possible to use CoAP over TCP (according to RFC)
+
+The caller have to check results and treat COAP_NOT_ENOUGH_DATA according to
+underlying protocol:
+
+- in case of UDP COAP_NOT_ENOUGH_DATA means COAP_FORMAT_ERROR,
+- in case of TCP client can try to receive more data
+
+Return value: see `mg_coap_send_message()` 
+

docs/c-api/coap.h/mg_coap_send_ack.md

+---
+title: "mg_coap_send_ack()"
+decl_name: "mg_coap_send_ack"
+symbol_kind: "func"
+signature: |
+  uint32_t mg_coap_send_ack(struct mg_connection *nc, uint16_t msg_id);
+---
+
+Compose CoAP acknowledgement from `mg_coap_message`
+and send it into `nc` connection.
+Return value: see `mg_coap_send_message()` 
+

docs/c-api/coap.h/mg_coap_send_message.md

+---
+title: "mg_coap_send_message()"
+decl_name: "mg_coap_send_message"
+symbol_kind: "func"
+signature: |
+  uint32_t mg_coap_send_message(struct mg_connection *nc,
+                                struct mg_coap_message *cm);
+---
+
+Compose CoAP message from `mg_coap_message`
+and send it into `nc` connection.
+Return 0 on success. On error, it is a bitmask:
+
+- `#define MG_COAP_ERROR 0x10000`
+- `#define MG_COAP_FORMAT_ERROR (MG_COAP_ERROR | 0x20000)`
+- `#define MG_COAP_IGNORE (MG_COAP_ERROR | 0x40000)`
+- `#define MG_COAP_NOT_ENOUGH_DATA (MG_COAP_ERROR | 0x80000)`
+- `#define MG_COAP_NETWORK_ERROR (MG_COAP_ERROR | 0x100000)` 
+

docs/c-api/coap.h/mg_set_protocol_coap.md

+---
+title: "mg_set_protocol_coap()"
+decl_name: "mg_set_protocol_coap"
+symbol_kind: "func"
+signature: |
+  int mg_set_protocol_coap(struct mg_connection *nc);
+---
+
+Set CoAP protocol handler - trigger CoAP specific events 
+

docs/c-api/coap.h/struct_mg_coap_message.md

+---
+title: "struct mg_coap_message"
+decl_name: "struct mg_coap_message"
+symbol_kind: "struct"
+signature: |
+  struct mg_coap_message {
+    uint32_t flags;
+    uint8_t msg_type;
+    uint8_t code_class;
+    uint8_t code_detail;
+    uint16_t msg_id;
+    struct mg_str token;
+    struct mg_coap_option *options;
+    struct mg_str payload;
+    struct mg_coap_option *optiomg_tail;
+  };
+---
+
+CoAP message. See RFC 7252 for details. 
+

docs/c-api/coap.h/struct_mg_coap_option.md

+---
+title: "struct mg_coap_option"
+decl_name: "struct mg_coap_option"
+symbol_kind: "struct"
+signature: |
+  struct mg_coap_option {
+    struct mg_coap_option *next;
+    uint32_t number;
+    struct mg_str value;
+  };
+---
+
+CoAP options.
+Use mg_coap_add_option and mg_coap_free_options
+for creation and destruction. 
+

docs/c-api/dns-server.h/intro.md

+---
+title: "DNS server"
+symbol_kind: "intro"
+decl_name: "dns-server.h"
+---
+
+Disabled by default; enable with `-DMG_ENABLE_DNS_SERVER`.
+

docs/c-api/dns-server.h/items.json

+{
+    "items": [
+        {
+            "type": "markdown",
+            "name": "intro.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_dns_create_reply.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_dns_reply_record.md"
+        },
+        {
+            "type": "markdown",
+            "name": "mg_dns_send_reply.md"
+        }
+    ]
+}

docs/c-api/dns-server.h/mg_dns_create_reply.md

+---
+title: "mg_dns_create_reply()"
+decl_name: "mg_dns_create_reply"
+symbol_kind: "func"
+signature: |
+  struct mg_dns_reply mg_dns_create_reply(struct mbuf *io,
+                                          struct mg_dns_message *msg);
+---
+
+Create a DNS reply.
+
+The reply will be based on an existing query message `msg`.
+The query body will be appended to the output buffer.
+"reply + recursion allowed" will be added to the message flags and
+message's num_answers will be set to 0.
+
+Answer records can be appended with `mg_dns_send_reply` or by lower
+level function defined in the DNS API.
+
+In order to send the reply use `mg_dns_send_reply`.
+It's possible to use a connection's send buffer as reply buffers,
+and it will work for both UDP and TCP connections.
+
+Example:
+
+```c
+reply = mg_dns_create_reply(&nc->send_mbuf, msg);
+for (i = 0; i < msg->num_questions; i++) {
+  rr = &msg->questions[i];
+  if (rr->rtype == MG_DNS_A_RECORD) {
+    mg_dns_reply_record(&reply, rr, 3600, &dummy_ip_addr, 4);
+  }
+}
+mg_dns_send_reply(nc, &reply);
+``` 
+