update documentation and translations again

4 files changed, 131 insertions, 27 deletions

diff --git a/shared-bindings/network/__init__.c b/shared-bindings/network/__init__.c
index c5639b462..69f8bea60 100644
--- a/shared-bindings/network/__init__.c
+++ b/shared-bindings/network/__init__.c
@@ -36,18 +36,23 @@
 
 #include "shared-bindings/network/__init__.h"
 
+#if MICROPY_PY_NETWORK
+
 //| :mod:`network` --- Network Interface Management
 //| ===============================================
 //|
 //| .. module:: network
 //|   :synopsis: Network Interface Management
 //|   :platform: SAMD
-
-#if MICROPY_PY_NETWORK
-
-/// \module network - network configuration
-///
-/// This module provides a registry of configured NICs.
+//|
+//| This module provides a registry of configured NICs.
+//| It is used by the 'socket' module to look up a suitable
+//| NIC when a socket is created.
+//|
+//| .. function:: route
+//|
+//|   Returns a list of all configured NICs.
+//|
 
 STATIC mp_obj_t network_route(void) {
     return MP_OBJ_FROM_PTR(&MP_STATE_PORT(mod_network_nic_list));
diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c
index f6949b4bf..d860c40c8 100644
--- a/shared-bindings/socket/__init__.c
+++ b/shared-bindings/socket/__init__.c
@@ -44,11 +44,22 @@
 //|   :synopsis: TCP, UDP and RAW sockets
 //|   :platform: SAMD21, SAMD51
 //|
-//| XXX TODO Write Docs.
+//| Create TCP, UDP and RAW sockets for communicating over the Internet.
+//|   
 
 STATIC const mp_obj_type_t socket_type;
 
-// constructor socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)
+//| .. currentmodule:: socket
+//|
+//| .. class:: socket(family, type, proto, ...)
+//|   
+//|   Create a new socket
+//|
+//|   :param ~int family: AF_INET or AF_INET6
+//|   :param ~int type: SOCK_STREAM, SOCK_DGRAM or SOCK_RAW
+//|   :param ~int proto: IPPROTO_TCP, IPPROTO_UDP or IPPROTO_RAW (ignored)
+//|
+
 STATIC mp_obj_t socket_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
     mp_arg_check_num(n_args, n_kw, 0, 4, false);
 
@@ -87,7 +98,13 @@ STATIC void socket_select_nic(mod_network_socket_obj_t *self, const byte *ip) {
     }
 }
 
-// method socket.bind(address)
+//| .. method:: bind(address)
+//|
+//|   Bind a socket to an address
+//|
+//|   :param ~tuple address: tuple of (remote_address, remote_port)
+//|
+
 STATIC mp_obj_t socket_bind(mp_obj_t self_in, mp_obj_t addr_in) {
     mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in);
 
@@ -108,7 +125,13 @@ STATIC mp_obj_t socket_bind(mp_obj_t self_in, mp_obj_t addr_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_bind_obj, socket_bind);
 
-// method socket.listen(backlog)
+//| .. method:: listen(backlog)
+//|
+//|   Set socket to listen for incoming connections
+//|
+//|   :param ~int backlog: length of backlog queue for waiting connetions
+//|
+
 STATIC mp_obj_t socket_listen(mp_obj_t self_in, mp_obj_t backlog) {
     mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in);
 
@@ -127,7 +150,13 @@ STATIC mp_obj_t socket_listen(mp_obj_t self_in, mp_obj_t backlog) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_listen_obj, socket_listen);
 
-// method socket.accept()
+//| .. method:: accept()
+//|
+//|   Accept a connection on a listening socket of type SOCK_STREAM,
+//|   creating a new socket of type SOCK_STREAM.
+//|   Returns a tuple of (new_socket, remote_address)
+//|
+
 STATIC mp_obj_t socket_accept(mp_obj_t self_in) {
     mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in);
 
@@ -159,7 +188,13 @@ STATIC mp_obj_t socket_accept(mp_obj_t self_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(socket_accept_obj, socket_accept);
 
-// method socket.connect(address)
+//| .. method:: connect(address)
+//|
+//|   Connect a socket to a remote address
+//|
+//|   :param ~tuple address: tuple of (remote_address, remote_port)
+//|
+
 STATIC mp_obj_t socket_connect(mp_obj_t self_in, mp_obj_t addr_in) {
     mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in);
 
@@ -180,7 +215,14 @@ STATIC mp_obj_t socket_connect(mp_obj_t self_in, mp_obj_t addr_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_connect_obj, socket_connect);
 
-// method socket.send(bytes)
+//| .. method:: send(bytes)
+//|
+//|   Send some bytes to the connected remote address.
+//|   Suits sockets of type SOCK_STREAM
+//|
+//|   :param ~bytes bytes: some bytes to send
+//|
+
 STATIC mp_obj_t socket_send(mp_obj_t self_in, mp_obj_t buf_in) {
     mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in);
     if (self->nic == MP_OBJ_NULL) {
@@ -198,7 +240,14 @@ STATIC mp_obj_t socket_send(mp_obj_t self_in, mp_obj_t buf_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_send_obj, socket_send);
 
-// method socket.recv(bufsize)
+//| .. method:: recv(bufsize)
+//|
+//|   Reads some bytes from the connected remote address.
+//|   Suits sockets of type SOCK_STREAM
+//|   Returns a bytes() of length <= bufsize
+//| 
+//|   :param ~int bufsize: maximum number of bytes to receive  
+
 STATIC mp_obj_t socket_recv(mp_obj_t self_in, mp_obj_t len_in) {
     mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in);
     if (self->nic == MP_OBJ_NULL) {
@@ -221,7 +270,15 @@ STATIC mp_obj_t socket_recv(mp_obj_t self_in, mp_obj_t len_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_recv_obj, socket_recv);
 
-// method socket.sendto(bytes, address)
+//| .. method:: sendto(bytes, address)
+//|
+//|   Send some bytes to a specific address.
+//|   Suits sockets of type SOCK_DGRAM
+//|
+//|   :param ~bytes bytes: some bytes to send
+//|   :param ~tuple address: tuple of (remote_address, remote_port)
+//|
+
 STATIC mp_obj_t socket_sendto(mp_obj_t self_in, mp_obj_t data_in, mp_obj_t addr_in) {
     mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in);
 
@@ -247,7 +304,18 @@ STATIC mp_obj_t socket_sendto(mp_obj_t self_in, mp_obj_t data_in, mp_obj_t addr_
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_3(socket_sendto_obj, socket_sendto);
 
-// method socket.recvfrom(bufsize)
+//| .. method:: recvfrom(bufsize)
+//|
+//|   Reads some bytes from the connected remote address.
+//|   Suits sockets of type SOCK_STREAM
+//|
+//|   Returns a tuple containing
+//|   * a bytes() of length <= bufsize
+//|   * a remote_address, which is a tuple of ip address and port number
+//|
+//|   :param ~int bufsize: maximum number of bytes to receive  
+//|
+
 STATIC mp_obj_t socket_recvfrom(mp_obj_t self_in, mp_obj_t len_in) {
     mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in);
     if (self->nic == MP_OBJ_NULL) {
@@ -275,7 +343,11 @@ STATIC mp_obj_t socket_recvfrom(mp_obj_t self_in, mp_obj_t len_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_recvfrom_obj, socket_recvfrom);
 
-// method socket.setsockopt(level, optname, value)
+//| .. method:: setsockopt(level, optname, value)
+//|
+//|   Sets socket options
+//|
+
 STATIC mp_obj_t socket_setsockopt(size_t n_args, const mp_obj_t *args) {
     mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(args[0]);
 
@@ -305,10 +377,13 @@ STATIC mp_obj_t socket_setsockopt(size_t n_args, const mp_obj_t *args) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(socket_setsockopt_obj, 4, 4, socket_setsockopt);
 
-// method socket.settimeout(value)
-// timeout=0 means non-blocking
-// timeout=None means blocking
-// otherwise, timeout is in seconds
+//| .. method:: settimeout(value)
+//|
+//|   Set the timeout value for this socket.
+//|
+//|   :param ~int value: timeout in seconds.  0 means non-blocking.  None means block indefinitely.
+//|
+
 STATIC mp_obj_t socket_settimeout(mp_obj_t self_in, mp_obj_t timeout_in) {
     mod_network_socket_obj_t *self = MP_OBJ_TO_PTR(self_in);
     if (self->nic == MP_OBJ_NULL) {
@@ -333,6 +408,13 @@ STATIC mp_obj_t socket_settimeout(mp_obj_t self_in, mp_obj_t timeout_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_2(socket_settimeout_obj, socket_settimeout);
 
+//| .. method:: setblocking(flag)
+//|
+//|   Set the blocking behaviour of this socket.
+//|
+//|   :param ~bool flag: False means non-blocking, True means block indefinitely.
+//|
+
 // method socket.setblocking(flag)
 STATIC mp_obj_t socket_setblocking(mp_obj_t self_in, mp_obj_t blocking) {
     if (mp_obj_is_true(blocking)) {
@@ -386,8 +468,14 @@ STATIC const mp_obj_type_t socket_type = {
     .locals_dict = (mp_obj_dict_t*)&socket_locals_dict,
 };
 
-/******************************************************************************/
-// usocket module
+//| .. function:: getaddrinfo(host, port)
+//| 
+//|   Gets the address information for a hostname and port
+//|
+//|   Returns the appropriate family, socket type, socket protocol and 
+//|   address information to call socket.socket() and socket.connect() with,
+//|   as a tuple.
+//|
 
 STATIC mp_obj_t socket_getaddrinfo(mp_obj_t host_in, mp_obj_t port_in) {
     size_t hlen;
diff --git a/shared-bindings/wiznet/__init__.c b/shared-bindings/wiznet/__init__.c
index 342cb1052..e230deecc 100644
--- a/shared-bindings/wiznet/__init__.c
+++ b/shared-bindings/wiznet/__init__.c
@@ -42,7 +42,7 @@
 //|   :synopsis: Support for WizNet hardware
 //|   :platform: SAMD
 //|
-//| Doc content goes here
+//| Support for WizNet hardware, including the WizNet 5500 Ethernet adaptor.
 //|
 //| Libraries
 //|
diff --git a/shared-bindings/wiznet/wiznet5k.c b/shared-bindings/wiznet/wiznet5k.c
index 32f100969..1dba5f380 100644
--- a/shared-bindings/wiznet/wiznet5k.c
+++ b/shared-bindings/wiznet/wiznet5k.c
@@ -53,6 +53,10 @@
 //| .. class:: WIZNET5K(spi, cs, rst)
 //|
 //|   Create a new WIZNET5500 interface using the specified pins
+//|   
+//|   :param spi: spi bus to use
+//|   :param cs: pin to use for Chip Select
+//|   :param rst: pin to sue for Reset 
 //|
 
 STATIC mp_obj_t wiznet5k_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
@@ -68,9 +72,10 @@ STATIC mp_obj_t wiznet5k_connected_get_value(mp_obj_t self_in) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(wiznet5k_connected_get_value_obj, wiznet5k_connected_get_value);
 
-//| attribute:: connected
+//| .. attribute:: connected
 //|
 //|   is this device physically connected?
+//|
 
 const mp_obj_property_t wiznet5k_connected_obj = {
     .base.type = &mp_type_property,
@@ -79,8 +84,14 @@ const mp_obj_property_t wiznet5k_connected_obj = {
               (mp_obj_t)&mp_const_none_obj},
 };
 
-/// \method ifconfig([(ip, subnet, gateway, dns)])
-/// Get/set IP address, subnet mask, gateway and DNS.
+//| .. method:: ifconfig(...)
+//|
+//|   Called without parameters, returns a tuple of
+//|   (ip_address, subnet_mask, gateway_address, dns_server)
+//|
+//|   Or can be called with the same tuple to set those parameters.
+//|
+
 STATIC mp_obj_t wiznet5k_ifconfig(size_t n_args, const mp_obj_t *args) {
     wiz_NetInfo netinfo;
     ctlnetwork(CN_GET_NETINFO, &netinfo);