net: sockets: Add docstrings for BSD Sockets API #14912
Conversation
|
So, this is what I have in mind re: addressing #13397. Interested parties, please confirm that this satisfies your expectation, and I'll continue in the same vein with other functions/defines. |
pfalcon
changed the title
|
Example of rendered docs. |
|
All checks are passing now. Review history of this comment for details about previous failed status. |
pfalcon
force-pushed
the
sockets-docstrings
branch
from
09d53a4 to
81ae455
Compare
pfalcon
force-pushed
the
sockets-docstrings
branch
from
81ae455 to
687234e
Compare
pfalcon
added
bug
pfalcon
changed the title
|
Ok, hopefully this adds enough goodies. Ready for review. |
Codecov Report
@@ Coverage Diff @@
## master #14912 +/- ##
=======================================
Coverage 52.93% 52.93%
=======================================
Files 309 309
Lines 45251 45251
Branches 10447 10447
=======================================
Hits 23953 23953
Misses 16533 16533
Partials 4765 4765
Continue to review full report at Codecov.
|
dbkinder
left a comment
dbkinder
left a comment
There was a problem hiding this comment.
Doc changes look good, one edit.
include/net/socket_select.h
Outdated
There was a problem hiding this comment.
| * for normative description. This function is provided to ease porting | |
| * for normative description. This function is provided to ease porting of |
jukkar
left a comment
jukkar
left a comment
There was a problem hiding this comment.
Looks mostly good, couple of defines are still missing documentation in
https://builds.zephyrproject.org/zephyrproject-rtos/zephyr/14912/docs/reference/networking/sockets.html
like
ZSOCK_POLLIN
ZSOCK_POLLPRI
ZSOCK_POLLOUT
ZSOCK_POLLERR
ZSOCK_POLLHUP
ZSOCK_POLLNVAL
ZSOCK_MSG_PEEK
ZSOCK_MSG_DONTWAIT
ZSOCK_SHUT_RD
ZSOCK_SHUT_WR
ZSOCK_SHUT_RDWR
SOL_SOCKET
SO_REUSEADDR
SO_ERROR
TCP_NODELAY
IPV6_V6ONLY
ZSOCK_FD_SETSIZE
and
void ZSOCK_FD_ZERO(zsock_fd_set *set)
int ZSOCK_FD_ISSET(int fd, zsock_fd_set *set)
void ZSOCK_FD_CLR(int fd, zsock_fd_set *set)
void ZSOCK_FD_SET(int fd, zsock_fd_set *set)
Some of them might not need documentation, but in that case we should mark them internal using
/** @cond INTERNAL_HIDDEN */
xxx
/** @endcond */
c56b0a2 to
ccfe149
Compare
Ok, added more. Please keep in mind there's always something to improve in the documentation and "perfect is the enemy of good" ;-). |
I went through the networking documentation and these "empty" entries in the documentation look quite bad. So I was not really looking for perfect documentation here, just something that does not look bad when browsing the docs. |
|
By now, at least 90%, likely 95%, of entries which were empty, are no longer empty. |
|
Couple of defines are still missing text. Please either add some text there or mark them internal so they get hidden. |
dbkinder
left a comment
dbkinder
left a comment
There was a problem hiding this comment.
doc changes LGTM, thanks!
The current idea is that we document zsock_* prefixed symbols, refer to Open Group POSIX website (http://pubs.opengroup.org/onlinepubs/9699919799/) for normative descriptions, and explicitly mention bare POSIX name of a function too (so e.g. users could find it via search). Fixes: zephyrproject-rtos#13397 Signed-off-by: Paul Sokolovsky <paul.sokolovsky@linaro.org>
pfalcon
force-pushed
the
sockets-docstrings
branch
from
ccfe149 to
3147bb3
Compare
Ok, added something for those too. P.S. I'm on vacation next week, and hopefully did everything so this could fit into 1.14. |
6 participants
The current idea is that we document zsock_* prefixed symbols, refer
to Open Group POSIX website
(http://pubs.opengroup.org/onlinepubs/9699919799/) for normative
descriptions, and explicitly mention bare POSIX name of a function
too (so e.g. users could find it via search).
Fixes: #13397
Signed-off-by: Paul Sokolovsky paul.sokolovsky@linaro.org