From 55c18947bd35268658e7b8a5ac4b16421d485038 Mon Sep 17 00:00:00 2001 From: Ken Bannister Date: Sat, 14 Sep 2019 08:13:50 -0400 Subject: [PATCH 1/4] net/nanocoap: doc emphasize application API --- sys/include/net/nanocoap.h | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/sys/include/net/nanocoap.h b/sys/include/net/nanocoap.h index d239a6a4f1..29cb0d6032 100644 --- a/sys/include/net/nanocoap.h +++ b/sys/include/net/nanocoap.h @@ -19,13 +19,16 @@ * 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 + * + * 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 * From 0c5706969cb861edf2537f6dc6c7ccb207c649ae Mon Sep 17 00:00:00 2001 From: Ken Bannister Date: Sat, 14 Sep 2019 08:18:00 -0400 Subject: [PATCH 2/4] net/nanocoap: refactor Options API doc --- sys/include/net/nanocoap.h | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/sys/include/net/nanocoap.h b/sys/include/net/nanocoap.h index 29cb0d6032..84a66d822f 100644 --- a/sys/include/net/nanocoap.h +++ b/sys/include/net/nanocoap.h @@ -30,24 +30,16 @@ * server with lesser resource requirements, and [gcoap](group__net__gcoap.html) * provides a more featureful messaging hub. * - * ## Option APIs + * ### 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_. * * ## Server path matching * @@ -779,7 +771,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 Encode the given uint option into pkt * @@ -870,6 +867,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. */ /**@{*/ /** From 3497c67917cbbe32b73370232b4432ee3114a53b Mon Sep 17 00:00:00 2001 From: Ken Bannister Date: Sat, 14 Sep 2019 08:18:51 -0400 Subject: [PATCH 3/4] net/gcoap: refactor Options API doc --- sys/include/net/gcoap.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sys/include/net/gcoap.h b/sys/include/net/gcoap.h index 09cfb99bfb..cddac14222 100644 --- a/sys/include/net/gcoap.h +++ b/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 also supports the Observe extension (RFC 7641) for a server. gcoap * provides functions to generate and send an observe notification that are From 1ea66c713b76985b692430ef0c03aade0885b6a9 Mon Sep 17 00:00:00 2001 From: Ken Bannister Date: Sat, 14 Sep 2019 08:19:12 -0400 Subject: [PATCH 4/4] net/nanocoap_sock: refactor Options API doc --- sys/include/net/nanocoap_sock.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sys/include/net/nanocoap_sock.h b/sys/include/net/nanocoap_sock.h index 5e72ff002a..88e3541562 100644 --- a/sys/include/net/nanocoap_sock.h +++ b/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 ## *