[riot-notifications] [RIOT-OS/RIOT] nanocoap docs: buffer/packet API distinction not referenced when used (#12201)

Ken Bannister notifications at github.com
Fri Sep 13 15:08:28 CEST 2019

Sorry to hear about this confusion in the documentation. There was a significant change in the documentation structure with #10876:

- Grouped functions in nanocoap.h, which became more of a reference page
- Moved how to use the Buffer API to nanocoap_sock.h, which previously just listed the functions for nanocoap sock.

The nanocoap sock page does say to use the Buffer API, and the gcoap page says to use the coap_opt_add_...() functions, which are the Packet API. The intention with the description of the Option APIs remaining on the nanocoap page was just to introduce them, since they are used in the function groups. However, I agree that information was lost, and we should make these relationships clearer. 

Prior to this PR, the nanocoap.h documentation included quite some detail on the Buffer API vs. Packet API. I definitely suggest looking at this older version.

There really are two separate dimensions here:

- Buffer API vs. Packet API (how to write a message)
- nanocoap sock vs. gcoap (how to send/receive a message)

In other words it should be possible to choose independently how to write a message vs. how to send/receive it. However at present, as a practical matter, I found it simpler to just say: Buffer API is for nanocoap sock, and Packet API is for gcoap. 

I am pretty happy with the gcoap page now because I think it is easy to follow the steps to write a message, _especially_ with the addition of block in #11057. (Try building the doc for that PR.) We can revisit this, but I would be concerned about the effort to make the distinction for write vs. send/receive clear and simple to follow. Also, I found it difficult to explain the Buffer API as a full on alternative because it has just sort of grown a function at a time.

So, with that background a few suggestions:

- nanocoap.h -- in the Options API section say that nanocoap sock uses the Buffer API and gcoap uses the Packet API
- gcoap.h -- specifically say it uses the Packet API, and add the sentence below
- nanocoap.h -- add the sentence below

> The caller must write options in order by option number (see "CoAP option numbers" in [CoAP defines](group__net__coap.html)).

You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20190913/51df1d32/attachment.htm>

More information about the notifications mailing list