net/nanocoap: group functions in module doc#10876
Conversation
badbc95 to
5c0f331
Compare
|
I just revised this PR to include splitting documentation for the Buffer API to a new module section, Nanocoap Sock. This section of the documentation already included use of nanocoap_sock functions like nanocoap_server() and nanocoap_request(), so it seemed like organic growth. The reorganization of the function documentation means it touches work in currently open PRs, as well as PRs for work I am doing to complete Block for #10732. So, I have imposed an ordering on the PRs, with this one after #10931, the last in the currently open sequence. I'm not looking forward to rebasing, but this approach makes it easier to keep track of the changes. |
5c0f331 to
f4f0043
Compare
|
please rebase! |
|
I agree with the function grouping. Makes much more sense. IMO we should make the nanocoap sock documentation a subgroup of the main nanocoap group, and call it the "high-level API". I think it would make sense to steer any users towards that, as most will probably be looking for "how to make a client request" or "how to start serving a coap resource". |
Is that in scope or should we go with the re-ordering first? |
|
With this PR, the documentation is divided into three groups:
These sections are siblings beneath Modules > Networking. The nanocoap and nanocoap sock docs are beside each other, so they should be easy to find. In addition both the high level and low level docs have links to each other. I'm not sure exactly what you mean by making the nanocoap sock documentation a 'subgroup' of nanocoap, but I think the present arrangement provides a logical separation. I would defer any further shuffling until later. Next step is to rebase. Thanks for reviewing. |
f4f0043 to
50aeaa9
Compare
|
Rebased. |
Ok! |
50aeaa9 to
6b58039
Compare
|
Rebased to incorporate changes from #11386. This PR is prone to conflicts, let's get it merged! |
| * path, specifically the ASCII encoding of the path characters (digit and | ||
| * capital precede lower case). nanocoap provides the | ||
| * COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER entry for `/.well-known/core`. | ||
| * |
There was a problem hiding this comment.
The path matching section is missing here.
There was a problem hiding this comment.
Good catch, Leandro!
I left the path matching section in the base nanocoap doc and added references in the nanocoap sock and gcoap docs. There was too much text in that section to duplicate.
leandrolanzieri
left a comment
There was a problem hiding this comment.
Just two minor comments, otherwise looks good. I like the grouping!
| * | ||
| * See the nanocoap_server example, which is built on the nanocoap_server() | ||
| * function. A server must define an array of coap_resource_t resources for | ||
| * which it responds. See the declarations of `coap_resources` and |
There was a problem hiding this comment.
Would it be possible to add a link to coap_resources and coap_resources_numof?
| @@ -46,7 +46,8 @@ | |||
| * structs) ordered by the resource path, specifically the ASCII encoding of | |||
There was a problem hiding this comment.
I know this did not change in this PR, but we are touching the doc already so: Where it says "Internally, gcoap depends on the nanocoap package for base level structs and functionality" a link to nanocoap could be handy, as it is the first reference to it in the document.
Also, maybe change 'package' to module? as package usually refers to external packages in RIOT.
|
@leandrolanzieri would you mind postponing your change requests for a follow-up PR? This is a dependency of a couple of other coap PR's I'd like to get on with... |
Changes postponed for a follow-up PR
|
Thanks, @leandrolanzieri. I'll squash the fix, and then we just need a green check mark from someone. ;-) |
bb7b63d to
5fc86c9
Compare
|
Squashed! |
net/nanocoap: reorganize module doc
Contribution description
It is difficult to use the nanocoap function documentation. There are now 52 public functions, not in alphabetic order. This PR organizes these functions into groups, sorts them within each group, and updates the module documentation to reference them. See the list below.
The groups also use a new name for the two APIs for writing a message: Buffer API and Packet API. Previously they were called the minimal API and struct-based API. I have struggled with these names for a while, but I think the new ones are simple and clear.
The next sequence of PRs implement the remainder of Block, including for the Packet API. We plan to complete the documentation for Block with those PRs. So, to make it easier to read the module documentation, the current PR moves the guide to using the Buffer API and the nanocoap_sock functions to that header. Otherwise, the nanocoap page will become overloaded and harder to follow.
Function groups:
Testing procedure
make docSee both the Nanocoap and Nanocoap Sock sections.
Issues/PRs references
Depends on #10931 to order the open PRs