fixup! sock: doc fixes

Address
RIOT-OS#5884 (review)

sys/include/net/sock.h

@@ -35,7 +35,7 @@
  *
  * This module provides a set of functions to establish connections or send and
  * receive datagrams using different types of protocols. Together, they serve as
- * an API allows an application or library to connect to a network.
+ * an API that allows an application or library to connect to a network.
  *
  * It was designed with the following priorities in mind
  *
@@ -76,9 +76,9 @@
  * Implementors Notes
  * ==================
  * ### Type definition
- * For simplicity and modularity this API doesn't put any restriction of the
+ * For simplicity and modularity this API doesn't put any restriction on the
  * actual implementation of the type. For example, one implementation might
- * choose to have all `sock` types have a common base class or use the raw IP
+ * choose to have all `sock` types having a common base class or use the raw IP
  * `sock` type to send e.g. UDP packets, while others will keep them
  * completely separate from each other.
  *

sys/include/net/sock/ip.h

@@ -75,9 +75,9 @@
  * uint8_t buf[128];
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
- * To be able to listen for incoming packets we want to bind the sock so we need
- * to set a local end point (even if we just state here, that we just want to
- * bind it to any IPv6 address).
+ * To be able to listen for incoming packets we bind the `sock` by setting a
+ * local end point (even if we just state here, that we just want to bind it to
+ * any IPv6 address).
  *
  * We then proceed to create the `sock`. It is bound to `local` and listens for
  * IPv6 packets with @ref ipv6_hdr_t::nh "next header field"
@@ -94,10 +94,11 @@
  *     }
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
- * We then wait indefinitely for an incoming message in `buf` from `remote`.
- * If we want to timeout this wait period we could alternatively set the
- * `timeout` parameter of @ref sock_ip_recv() to a value `> 0`.
- * If an error occurs on receive we just ignore it and continue looping.
+ * The application then waits indefinitely for an incoming message in
+ * `buf` from `remote`. If we want to timeout this wait period we could
+ * alternatively set the `timeout` parameter of @ref sock_ip_recv() to a
+ * value `> 0`. If an error occurs on receive we just ignore it and continue
+ * looping.
  *
  * If we receive a message we use its `remote` to reply. Note since the `proto`
  * was already set during @ref sock_ip_create() we can just leave `proto` for
@@ -127,9 +128,9 @@
  * res = sock_ip_send(NULL, data, data_len, PROTNUM, &remote);
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
- * With `data` being the data send, `data_len` the length of `data`, `PROTNUM`
- * the next header number for the send packet and `remote` the remote end point
- * the packet is to be sent.
+ * With `data` being the data sent, `data_len` the length of `data`, `PROTNUM`
+ * the next header number for the sent packet and `remote` the remote end point
+ * the packet that is to be sent.
  *
  * To see some other utilization we look at a more complex example in form of
  * the counter of the echo server above:
@@ -196,8 +197,8 @@
  * @ref net_gnrc GNRC) and at least one network device.
  *
  * We first create again a `sock` with a local end point bound to any IPv6
- * address. Note that we also could set the remote here and not use it with
- * @ref sock_ip_send().
+ * address. Note that we also could specify the remote end point here and not
+ * use it with @ref sock_ip_send().
  *
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.c}
  *     sock_ip_ep_t local = SOCK_IPV6_EP_ANY;
@@ -319,8 +320,8 @@ typedef struct sock_ip sock_ip_t;
  *          other (i.e. `(local->netif != remote->netif) &&
  *          ((local->netif != SOCK_ADDR_ANY_NETIF) ||
  *          (remote->netif != SOCK_ADDR_ANY_NETIF))` if neither is `NULL`).
- * @return  -ENOMEM, if not enough resources for `sock` to be created can be
- *          provided.
+ * @return  -ENOMEM, if not enough resources can be provided for `sock` to be
+ *          created.
  * @return  -EPROTONOSUPPORT, if `local != NULL` or `remote != NULL` and
  *          proto is not supported by sock_ip_ep_t::family of @p local or @p
  *          remote.

sys/include/net/sock/udp.h

@@ -74,13 +74,13 @@
  * uint8_t buf[128];
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
- * To be able to listen for incoming packets we want to bind the sock so we need
- * to set a local end point with a port (`12345` in this case).
+ * To be able to listen for incoming packets we bind the `sock` by setting a
+ * local end point with with a port (`12345` in this case).
  *
  * We then proceed to create the `sock`. It is bound to `local` and thus listens
  * for UDP packets with @ref udp_hdr_t::dst_port "destination port" `12345`.
  * Since we don't need any further configuration we set the flags to 0.
-* In case of an error we stop the program:
+ * In case of an error we stop the program:
  *
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.c}
  *     sock_udp_ep_t local = SOCK_IPV6_EP_ANY;
@@ -94,10 +94,11 @@
  *     }
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
- * We then wait indefinitely for an incoming message in `buf` from `remote`.
- * If we want to timeout this wait period we could alternatively set the
- * `timeout` parameter of @ref sock_udp_recv() to a value `> 0`.
- * If an error occurs on receive we just ignore it and continue looping.
+ * The application then waits indefinitely for an incoming message in
+ * `buf` from `remote`. If we want to timeout this wait period we could
+ * alternatively set the `timeout` parameter of @ref sock_udp_recv() to a
+ * value `> 0`. If an error occurs on receive we just ignore it and continue
+ * looping.
  *
  * If we receive a message we use its `remote` to reply. In case of an error on
  * send we print an according message:
@@ -125,8 +126,8 @@
  * res = sock_udp_send(NULL, data, data_len, &remote);
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
- * With `data` being the data send, `data_len` the length of `data` and `remote`
- * the remote end point the packet is to be sent.
+ * With `data` being the data sent, `data_len` the length of `data` and `remote`
+ * the remote end point the packet that is is to be sent.
  *
  * To see some other utilization we look at a more complex example in form of
  * the counter of the echo server above:
@@ -196,8 +197,8 @@
  * @ref net_gnrc GNRC) and at least one network device.
  *
  * We first create again a `sock` with a local end point bound to any IPv6
- * address and some port. Note that we also could set the remote here and not
- * use it with @ref sock_udp_send().
+ * address and some port. Note that we also could specify the remote here and
+ * not use it with @ref sock_udp_send().
  *
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.c}
  *     sock_udp_ep_t local = SOCK_IPV6_EP_ANY;
@@ -325,8 +326,8 @@ typedef struct sock_udp sock_udp_t;
  *          `(local->netif != remote->netif) &&
  *          ((local->netif != SOCK_ADDR_ANY_NETIF) ||
  *          (remote->netif != SOCK_ADDR_ANY_NETIF))` if neither is `NULL`).
- * @return  -ENOMEM, if the implementation can't provide enough resources for
- *          `sock` to be created.
+ * @return  -ENOMEM, if not enough resources can be provided for `sock` to be
+ *          created.
  */
 int sock_udp_create(sock_udp_t *sock, const sock_udp_ep_t *local,
                     const sock_udp_ep_t *remote, uint16_t flags);