Merge pull request #10657 from maribu/netdev_driver_pre

netdev_driver_t::recv(): Clarified documentation

drivers/include/net/netdev.h

@@ -310,19 +310,26 @@ typedef struct netdev_driver {
     int (*send)(netdev_t *dev, const iolist_t *iolist);
 
     /**
-     * @brief Get a received frame
+     * @brief Drop a received frame, **OR** get the length of a received frame,
+     *        **OR** get a received frame.
      *
      * @pre `(dev != NULL)`
-     * @pre `(buf != NULL) && (len > 0)`
      *
      * Supposed to be called from
      * @ref netdev_t::event_callback "netdev->event_callback()"
      *
-     * If @p buf == NULL and @p len == 0, returns the packet size without
-     * dropping it.
+     * If @p buf == NULL and @p len == 0, returns the packet size -- or an upper
+     * bound estimation of the size -- without dropping the packet.
      * If @p buf == NULL and @p len > 0, drops the packet and returns the packet
      * size.
      *
+     * If called with @p buf != NULL and @p len is smaller than the received
+     * packet:
+     *  - The received packet is dropped
+     *  - The content in @p buf becomes invalid. (The driver may use the memory
+     *    to implement the dropping - or may not change it.)
+     *  - `-ENOBUFS` is returned
+     *
      * @param[in]   dev     network device descriptor. Must not be NULL.
      * @param[out]  buf     buffer to write into or NULL to return the packet
      *                      size.
@@ -335,7 +342,7 @@ typedef struct netdev_driver {
      *
      * @return `-ENOBUFS` if supplied buffer is too small
      * @return number of bytes read if buf != NULL
-     * @return packet size if buf == NULL
+     * @return packet size (or upper bound estimation) if buf == NULL
      */
     int (*recv)(netdev_t *dev, void *buf, size_t len, void *info);