From 32c19d63e36aeae6e651fae44f863f155a8460e8 Mon Sep 17 00:00:00 2001
From: Martine Lenders <mail@martine-lenders.eu>
Date: Tue, 22 Nov 2016 14:57:21 +0100
Subject: [PATCH] netdev2: make doc for driver more precise

When working on #6121 I noticed that the documentation of the `netdev2`
driver part is not really precise. This fixes that.
---
 drivers/include/net/netdev2.h | 29 ++++++++++++++++++++++-------
 1 file changed, 22 insertions(+), 7 deletions(-)

diff --git a/drivers/include/net/netdev2.h b/drivers/include/net/netdev2.h
index 260bf2b827..b859f2de6d 100644
--- a/drivers/include/net/netdev2.h
+++ b/drivers/include/net/netdev2.h
@@ -131,17 +131,24 @@ typedef struct netdev2_driver {
     /**
      * @brief Send frame
      *
+     * @pre `(dev != NULL)`
+     * @pre `(count == 0) || (vector != NULL)`
+     *      (`(count != 0) => (vector != NULL)`)
+     *
      * @param[in] dev       network device descriptor
      * @param[in] vector    io vector array to send
      * @param[in] count     nr of entries in vector
      *
-     * @return nr of bytes sent, or <=0 on error
+     * @return number of bytes sent, or `< 0` on error
      */
     int (*send)(netdev2_t *dev, const struct iovec *vector, unsigned count);
 
     /**
      * @brief Get a received frame
      *
+     * @pre `(dev != NULL)`
+     * @pre `(buf != NULL) && (len > 0)`
+     *
      * Supposed to be called from @ref netdev2_t::event_callback().
      *
      * If buf == NULL and len == 0, returns the packet size without dropping it.
@@ -149,13 +156,13 @@ typedef struct netdev2_driver {
      *
      * @param[in]   dev     network device descriptor
      * @param[out]  buf     buffer to write into or NULL
-     * @param[in]   len     maximum nr. of bytes to read
+     * @param[in]   len     maximum number of bytes to read
      * @param[out] info     status information for the received packet. Might
      *                      be of different type for different netdev2 devices.
      *                      May be NULL if not needed or applicable.
      *
-     * @return <=0 on error
-     * @return nr of bytes read if buf != NULL
+     * @return `< 0` on error
+     * @return number of bytes read if buf != NULL
      * @return packet size if buf == NULL
      */
     int (*recv)(netdev2_t *dev, void *buf, size_t len, void *info);
@@ -163,13 +170,17 @@ typedef struct netdev2_driver {
     /**
      * @brief the driver's initialization function
      *
-     * @return <=0 on error, >0 on success
+     * @pre `(dev != NULL)`
+     *
+     * @return `< 0` on error, 0 on success
      */
     int (*init)(netdev2_t *dev);
 
     /**
      * @brief a driver's user-space ISR handler
      *
+     * @pre `(dev != NULL)`
+     *
      * This function will be called from a network stack's loop when being notified
      * by netdev2_isr.
      *
@@ -184,13 +195,15 @@ typedef struct netdev2_driver {
     /**
      * @brief   Get an option value from a given network device
      *
+     * @pre `(dev != NULL)`
+     *
      * @param[in]   dev     network device descriptor
      * @param[in]   opt     option type
      * @param[out]  value   pointer to store the option's value in
      * @param[in]   max_len maximal amount of byte that fit into @p value
      *
      * @return              number of bytes written to @p value
-     * @return              <0 on error
+     * @return              `< 0` on error, 0 on success
      */
     int (*get)(netdev2_t *dev, netopt_t opt,
                void *value, size_t max_len);
@@ -198,13 +211,15 @@ typedef struct netdev2_driver {
     /**
      * @brief   Set an option value for a given network device
      *
+     * @pre `(dev != NULL)`
+     *
      * @param[in] dev       network device descriptor
      * @param[in] opt       option type
      * @param[in] value     value to set
      * @param[in] value_len the length of @p value
      *
      * @return              number of bytes used from @p value
-     * @return              <0 on error
+     * @return              `< 0` on error, 0 on success
      */
     int (*set)(netdev2_t *dev, netopt_t opt,
                void *value, size_t value_len);