update documentation and translations again

13 files changed, 154 insertions, 50 deletions

diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst
index 2751db6c4..2115085a3 100644
--- a/docs/library/usocket.rst
+++ b/docs/library/usocket.rst
@@ -138,16 +138,16 @@ Constants
    Note that you don't need to specify these in a call to `usocket.socket()`,
    because `SOCK_STREAM` socket type automatically selects `IPPROTO_TCP`, and
    `SOCK_DGRAM` - `IPPROTO_UDP`. Thus, the only real use of these constants
-   is as an argument to `setsockopt()`.
+   is as an argument to `usocket.socket.setsockopt()`.
 
 .. data:: usocket.SOL_*
 
-   Socket option levels (an argument to `setsockopt()`). The exact
+   Socket option levels (an argument to `usocket.socket.setsockopt()`). The exact
    inventory depends on a ``MicroPython port``.
 
 .. data:: usocket.SO_*
 
-   Socket options (an argument to `setsockopt()`). The exact
+   Socket options (an argument to `usocket.socket.setsockopt()`). The exact
    inventory depends on a ``MicroPython port``.
 
 Constants specific to WiPy:
diff --git a/locale/circuitpython.pot b/locale/circuitpython.pot
index 6c2a10891..8fc817849 100644
--- a/locale/circuitpython.pot
+++ b/locale/circuitpython.pot
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2018-10-11 17:02+1100\n"
+"POT-Creation-Date: 2018-10-11 22:08+1100\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -2292,7 +2292,7 @@ msgstr ""
 msgid "RTC calibration is not supported on this board"
 msgstr ""
 
-#: shared-bindings/socket/__init__.c:428 shared-module/network/__init__.c:64
+#: shared-bindings/socket/__init__.c:516 shared-module/network/__init__.c:64
 msgid "no available NIC"
 msgstr ""
 
diff --git a/locale/de_DE.po b/locale/de_DE.po
index 1672ef178..3f7b22702 100644
--- a/locale/de_DE.po
+++ b/locale/de_DE.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2018-10-11 14:16+1100\n"
+"POT-Creation-Date: 2018-10-11 22:08+1100\n"
 "PO-Revision-Date: 2018-07-27 11:55-0700\n"
 "Last-Translator: Sebastian Plamauer\n"
 "Language-Team: \n"
@@ -2311,7 +2311,7 @@ msgstr ""
 msgid "RTC calibration is not supported on this board"
 msgstr ""
 
-#: shared-bindings/socket/__init__.c:428 shared-module/network/__init__.c:64
+#: shared-bindings/socket/__init__.c:516 shared-module/network/__init__.c:64
 msgid "no available NIC"
 msgstr ""
 
diff --git a/locale/en_US.po b/locale/en_US.po
index d26568310..8bc73ad5c 100644
--- a/locale/en_US.po
+++ b/locale/en_US.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2018-10-11 14:16+1100\n"
+"POT-Creation-Date: 2018-10-11 22:08+1100\n"
 "PO-Revision-Date: 2018-07-27 11:55-0700\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -2292,7 +2292,7 @@ msgstr ""
 msgid "RTC calibration is not supported on this board"
 msgstr ""
 
-#: shared-bindings/socket/__init__.c:428 shared-module/network/__init__.c:64
+#: shared-bindings/socket/__init__.c:516 shared-module/network/__init__.c:64
 msgid "no available NIC"
 msgstr ""
 
diff --git a/locale/es.po b/locale/es.po
index df8803425..ee97a192c 100644
--- a/locale/es.po
+++ b/locale/es.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2018-10-11 14:16+1100\n"
+"POT-Creation-Date: 2018-10-11 22:08+1100\n"
 "PO-Revision-Date: 2018-08-24 22:56-0500\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -2340,7 +2340,7 @@ msgstr ""
 msgid "RTC calibration is not supported on this board"
 msgstr ""
 
-#: shared-bindings/socket/__init__.c:428 shared-module/network/__init__.c:64
+#: shared-bindings/socket/__init__.c:516 shared-module/network/__init__.c:64
 msgid "no available NIC"
 msgstr ""
 
diff --git a/locale/fil.po b/locale/fil.po
index 6fe9adfe6..e432da717 100644
--- a/locale/fil.po
+++ b/locale/fil.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2018-10-11 14:16+1100\n"
+"POT-Creation-Date: 2018-10-11 22:08+1100\n"
 "PO-Revision-Date: 2018-08-30 23:04-0700\n"
 "Last-Translator: Timothy <me@timothygarcia.ca>\n"
 "Language-Team: fil\n"
@@ -2358,7 +2358,7 @@ msgstr "Hindi supportado ang RTC sa board na ito"
 msgid "RTC calibration is not supported on this board"
 msgstr "RTC calibration ay hindi supportado ng board na ito"
 
-#: shared-bindings/socket/__init__.c:428 shared-module/network/__init__.c:64
+#: shared-bindings/socket/__init__.c:516 shared-module/network/__init__.c:64
 msgid "no available NIC"
 msgstr ""
 
diff --git a/locale/fr.po b/locale/fr.po
index 1658d90ce..51d999a2c 100644
--- a/locale/fr.po
+++ b/locale/fr.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: 0.1\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2018-10-11 17:02+1100\n"
+"POT-Creation-Date: 2018-10-11 22:08+1100\n"
 "PO-Revision-Date: 2018-08-14 11:01+0200\n"
 "Last-Translator: Pierrick Couturier <arofarn@arofarn.info>\n"
 "Language-Team: fr\n"
@@ -2354,7 +2354,7 @@ msgstr "RTC non supportée sur cette carte"
 msgid "RTC calibration is not supported on this board"
 msgstr "calibration de la RTC non supportée sur cette carte"
 
-#: shared-bindings/socket/__init__.c:428 shared-module/network/__init__.c:64
+#: shared-bindings/socket/__init__.c:516 shared-module/network/__init__.c:64
 #, fuzzy
 msgid "no available NIC"
 msgstr "busio.UART n'est pas disponible"
@@ -2523,9 +2523,9 @@ msgid "too many arguments provided with the given format"
 msgstr "trop d'arguments fournis avec ce format"
 
 #, fuzzy
-#~ msgid "palette must be displayio.Palette"
-#~ msgstr "la palette doit être longue de 32 octets"
-
-#, fuzzy
 #~ msgid "value_size must be power of two"
 #~ msgstr "'len' doit être un multiple de 4"
+
+#, fuzzy
+#~ msgid "palette must be displayio.Palette"
+#~ msgstr "la palette doit être longue de 32 octets"
diff --git a/locale/it_IT.po b/locale/it_IT.po
index 907e9f8d1..b093a949a 100644
--- a/locale/it_IT.po
+++ b/locale/it_IT.po
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2018-10-11 14:15+1100\n"
+"POT-Creation-Date: 2018-10-11 22:08+1100\n"
 "PO-Revision-Date: 2018-10-02 16:27+0200\n"
 "Last-Translator: Enrico Paganin <enrico.paganin@mail.com>\n"
 "Language-Team: \n"
@@ -2344,7 +2344,7 @@ msgstr "RTC non supportato su questa scheda"
 msgid "RTC calibration is not supported on this board"
 msgstr "calibrazione RTC non supportata su questa scheda"
 
-#: shared-bindings/socket/__init__.c:428 shared-module/network/__init__.c:64
+#: shared-bindings/socket/__init__.c:516 shared-module/network/__init__.c:64
 #, fuzzy
 msgid "no available NIC"
 msgstr "busio.UART non ancora implementato"
diff --git a/locale/pt_BR.po b/locale/pt_BR.po
index e499821e1..c54983951 100644
--- a/locale/pt_BR.po
+++ b/locale/pt_BR.po
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2018-10-11 14:17+1100\n"
+"POT-Creation-Date: 2018-10-11 22:08+1100\n"
 "PO-Revision-Date: 2018-10-02 21:14-0000\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -2299,7 +2299,7 @@ msgstr "O RTC não é suportado nesta placa"
 msgid "RTC calibration is not supported on this board"
 msgstr "A calibração RTC não é suportada nesta placa"
 
-#: shared-bindings/socket/__init__.c:428 shared-module/network/__init__.c:64
+#: shared-bindings/socket/__init__.c:516 shared-module/network/__init__.c:64
 msgid "no available NIC"
 msgstr ""
 
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);