netdev: fix return value and precondition doc #10101
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
miri64
added
Type: enhancement
bergzand
requested changes
Oct 2, 2018
drivers/include/net/netdev.h
Outdated
| * @return `-ENOTSUP` if @p opt is not configurable for the | ||
| * device | ||
| * @return `-EINVAL` if @p value is invalid an invalid value | ||
| * for @p opt |
There was a problem hiding this comment.
This sentence doesn't parse for me.
There was a problem hiding this comment.
For me neither. Only drank weak coffee before that so that might be the cause ;-).
|
(Just noticed: this is PR #10101 🎉) |
bergzand
added
the
CI: ready for build
While reviewing RIOT-OS#9942 I noticed that the documentation on the netdev driver API is unclear and in some cases outright contradicting itself: > ``` > @return number of bytes used from @p value > @return `< 0` on error, 0 on success > ``` IMHO this is unacceptable for such a central API where communication This fixes a few things and also clarifies preconditions: - Specifies negative `errno`s clearly so all drivers return the same when required - Re-iterates parameter preconditions and special cases within the parameter documentation itself (might also help towards RIOT-OS#9805?) - Fixes contradictions within return value documentation - Adds missing parameter documentation on `init()`.
miri64
force-pushed
the
netdev/doc/fix-return-asserts
branch
from
679f352
to
aba75be
Compare
|
Squashed |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Contribution description
While reviewing #9942 I noticed that the documentation on the netdev
driver API is unclear and in some cases outright contradicting itself:
IMHO this is unacceptable for such a central API where communication
This fixes a few things and also clarifies preconditions:
errnos clearly so all drivers return the samewhen required
parameter documentation itself (might also help towards Misleading API in netdev driver #9805?)
init().Testing procedure
Compile documentation (
make doc) and see if everything is alright indoc/doxygen/html/structnetdev__driver.html.Issues/PRs references
Noticed in #9942. Might help clarify #9805.