Merge pull request #12231 from kb2ma/coap/refine_api_purpose

net/nanocoap: rebalance application vs. option API doc

sys/include/net/gcoap.h

@@ -22,7 +22,8 @@
  * gcoap allocates a RIOT message processing thread, so a single instance can
  * serve multiple applications. This approach also means gcoap uses a single UDP
  * port, which supports RFC 6282 compression. Internally, gcoap depends on the
- * nanocoap package for base level structs and functionality.
+ * nanocoap package for base level structs and functionality. gcoap uses
+ * nanocoap's Packet API to write message options.
  *
  * gcoap supports the Observe extension (RFC 7641) for a server. gcoap provides
  * functions to generate and send an observe notification that are similar to

sys/include/net/nanocoap.h

@@ -19,32 +19,27 @@
  * provides high and low level interfaces to CoAP options, including Block.
  *
  * nanocoap includes the core structs to store message information. It also
- * also provides support for sending and receiving messages, such as
- * coap_parse() to read an incoming message.
+ * provides helper functions for use before sending and after receiving a
+ * message, such as coap_parse() to read an incoming message.
  *
- * The documentation here mostly categorizes and lists the contents of
- * nanocoap. To use nanocoap in an application, see the APIs that are built
- * with it: [nanocoap sock](group__net__nanosock.html) and
- * [gcoap](group__net__gcoap.html).
+ * ## Application APIs
  *
- * ## Option APIs
+ * This page provides reference documentation for the contents of nanocoap. To
+ * use nanocoap in an application, see the functional APIs that are built with
+ * it. [nanocoap sock](group__net__nanosock.html) is for a targeted client or
+ * server with lesser resource requirements, and [gcoap](group__net__gcoap.html)
+ * provides a more featureful messaging hub.
+ *
+ * ### Option APIs
  *
  * For both server responses and client requests, CoAP uses an Option mechanism
  * to encode message metadata that is not required for each message. For
  * example, the resource URI path is required only for a request, and is encoded
  * as the Uri-Path option.
  *
- * nanocoap provides two APIs for writing CoAP options:
- *
- * - **Buffer API** requires only a reference to the buffer for the message.
- * However, the caller must provide the last option number written as well as
- * the buffer position. The caller is primarily responsible for tracking and
- * managing the space remaining in the buffer.
- *
- * - **Packet API** uses a coap_pkt_t struct to conveniently track each
- * option as it is written and prepare for any payload. The caller must monitor
- * space remaining in the buffer; however, the API *will not* write past the
- * end of the buffer, and returns -ENOSPC when it is full.
+ * nanocoap sock uses the simpler Buffer API, described in the section
+ * _Options Write Buffer API_. gcoap uses the more convenient Packet API,
+ * described in the section _Options Write Packet API_.
  *
  * For either API, the caller *must* write options in order by option number
  * (see "CoAP option numbers" in [CoAP defines](group__net__coap.html)).
@@ -805,7 +800,12 @@ static inline unsigned coap_szx2size(unsigned szx)
  * @name    Functions -- Options Write Packet API
  *
  * Use a coap_pkt_t struct to manage writing Options to the PDU.
+ *
+ * The caller must monitor space remaining in the buffer; however, the API
+ * *will not* write past the end of the buffer, and returns -ENOSPC when it is
+ * full.
  */
+/**@{*/
 /**
  * @brief   Add block option in descriptive use from a slicer object
  *
@@ -1002,6 +1002,10 @@ ssize_t coap_opt_finish(coap_pkt_t *pkt, uint16_t flags);
  * @name    Functions -- Options Write Buffer API
  *
  * Write PDU Options directly to the array of bytes for a message.
+ *
+ * The caller must provide the last option number written as well as the buffer
+ * position. The caller is primarily responsible for tracking and managing the
+ * space remaining in the buffer.
  */
 /**@{*/
 /**

sys/include/net/nanocoap_sock.h

@@ -17,7 +17,8 @@
  * interface to RIOT's sock networking API to read and write CoAP messages.
  * For a server, nanocoap sock accepts a list of resource paths with callbacks
  * for writing the response. For a client, nanocoap sock provides a function
- * to send a request and waits for the server response.
+ * to send a request and waits for the server response. nanocoap sock uses
+ * nanocoap's Buffer API to write message options.
  *
  * ## Server Operation ##
  *