nanocoap docs: buffer/packet API distinction not referenced when used

[chrysn]

Steps to reproduce the issue

Start building nanocoap packages using the Packet API which is advertised as one of the two possible APIs towards the nanocoap message.

Then have another look at your message using any of the coap_opt_get_* functions which all internally use coap_find_option.

Expected results

The documentation should have pointed out that all these functions require a message built with the buffer API. (For users who know the implementation that's kind of obvious, and in most cases it won't matter too much because read options are mostly used with incoming messages that were parsed into the Buffer API, but that's not explicit.)

The best indication the reader gets at this is that the section including the read options is labelled "Read options from a parsed packet".

Next steps

I'll file a PR based on the currently open changes like #12075 and #11488 -- @kb2ma, any other PRs I should look into before writing this?

[kb2ma]

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_sock.h -- add the sentence below

The caller must write options in order by option number (see "CoAP option numbers" in CoAP defines).

[kb2ma]

I took a stab at implemenation in #12231. I will create a separate PR to readd the direction to add options in order.

[kb2ma]

Added separate PR #12234 for documenting requirement to add CoAP options in order.

[kb2ma]

@chrysn, do the updates and explanation above resolve this issue for you?

[kb2ma]

No response, so closing. Feel free to reopen if not resolved.