This follows the usual convention of having the whole params in the device
struct instead of a pointer-to. This also eliminates the need to cast a
const to a non-const pointer in the init function.
Some drivers return on netdev_driver_t::recv() not the actual frame size, but
an upper bound estimation of it. The upper layer code is already prepared to
handle that. This brings the doc in sync with the code.
Clarified in the documentation how netdev_driver_t::recv() should behave in case
the size of the buffer in parameter buf (indicated by parameter len) is to small
to fit the received frame.
netdev_driver_t::recv does on of three things:
- Receive the frame
- Drop it
- Get (an estimation of) the size of the frame
The brief section of the documentation was changed to reflect this. (And it
starts with the least obvious thing in the hope readers of the API stumble upon
it...)
Removed the invalid precondition in netdev_driver_t::recv that the buffer never
NULL and the length positive. (In the "get message size" case both is wrong, in
the drop message case the first part is wrong.)
Changes include:
- Implementation of two power modes for the driver: low and high
- Redesign and API change to the description in tsl4531x.h
- Full documentation
- Changing file structure and implementation to fit best practices as
described in
https://github.com/RIOT-OS/RIOT/wiki/Guide%3A-Writing-a-device-driver-in-RIOT
- Including I2C addresses for the rest of the range
While reviewing #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 #9805?)
- Fixes contradictions within return value documentation
- Adds missing parameter documentation on `init()`.
- Add minimal usage instructions
- Ensure that the `bme_280_read_humidity` function (only available on
the BME280) is included in the documentation.
- Fix a typo
