docs/{framebuf,usocket}: Use markup adhering to the latest docs conventions.

pfalcon · pfalcon · commit 1942f0ceef23 · 2017-06-29T02:22:14.000+03:00
diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst
@@ -32,25 +32,25 @@ Constructors
 
     Construct a FrameBuffer object.  The parameters are:
 
-        - `buffer` is an object with a buffer protocol which must be large
+        - *buffer* is an object with a buffer protocol which must be large
           enough to contain every pixel defined by the width, height and
           format of the FrameBuffer.
-        - `width` is the width of the FrameBuffer in pixels
-        - `height` is the height of the FrameBuffer in pixels
-        - `format` specifies the type of pixel used in the FrameBuffer;
+        - *width* is the width of the FrameBuffer in pixels
+        - *height* is the height of the FrameBuffer in pixels
+        - *format* specifies the type of pixel used in the FrameBuffer;
           valid values are ``framebuf.MVLSB``, ``framebuf.RGB565``
           and ``framebuf.GS4_HMSB``. MVLSB is monochrome 1-bit color,
           RGB565 is RGB 16-bit color, and GS4_HMSB is grayscale 4-bit color.
           Where a color value c is passed to a method, c is a small integer
           with an encoding that is dependent on the format of the FrameBuffer.
-        - `stride` is the number of pixels between each horizontal line
-          of pixels in the FrameBuffer. This defaults to `width` but may
+        - *stride* is the number of pixels between each horizontal line
+          of pixels in the FrameBuffer. This defaults to *width* but may
           need adjustments when implementing a FrameBuffer within another
-          larger FrameBuffer or screen. The `buffer` size must accommodate
+          larger FrameBuffer or screen. The *buffer* size must accommodate
           an increased step size.
 
-    One must specify valid `buffer`, `width`, `height`, `format` and
-    optionally `stride`.  Invalid `buffer` size or dimensions may lead to
+    One must specify valid *buffer*, *width*, *height*, *format* and
+    optionally *stride*.  Invalid *buffer* size or dimensions may lead to
     unexpected errors.
 
 Drawing primitive shapes
@@ -64,8 +64,8 @@ The following methods draw shapes onto the FrameBuffer.
 
 .. method:: FrameBuffer.pixel(x, y[, c])
 
-    If `c` is not given, get the color value of the specified pixel.
-    If `c` is given, set the specified pixel to the given color.
+    If *c* is not given, get the color value of the specified pixel.
+    If *c* is given, set the specified pixel to the given color.
 
 .. method:: FrameBuffer.hline(x, y, w, c)
 .. method:: FrameBuffer.vline(x, y, h, c)
@@ -106,7 +106,7 @@ Other methods
 .. method:: FrameBuffer.blit(fbuf, x, y[, key])
 
     Draw another FrameBuffer on top of the current one at the given coordinates.
-    If `key` is specified then it should be a color integer and the
+    If *key* is specified then it should be a color integer and the
     corresponding color will be considered transparent: all pixels with that
     color value will not be drawn.
 
diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst
@@ -14,34 +14,34 @@ for comparison.
    :class: attention
 
    CPython used to have a ``socket.error`` exception which is now deprecated,
-   and is an alias of OSError. In MicroPython, use OSError directly.
+   and is an alias of `OSError`. In MicroPython, use `OSError` directly.
 
 .. admonition:: Difference to CPython
    :class: attention
 
    For efficiency and consistency, socket objects in MicroPython implement a stream
    (file-like) interface directly. In CPython, you need to convert a socket to
-   a file-like object using ``makefile()`` method. This method is still supported
+   a file-like object using `makefile()` method. This method is still supported
    by MicroPython (but is a no-op), so where compatibility with CPython matters,
    be sure to use it.
 
 Socket address format(s)
 ------------------------
 
 The functions below which expect a network address, accept it in the format of
-`(ipv4_address, port)`, where `ipv4_address` is a string with dot-notation numeric
+*(ipv4_address, port)*, where *ipv4_address* is a string with dot-notation numeric
 IPv4 address, e.g. ``"8.8.8.8"``, and port is integer port number in the range
-1-65535. Note the domain names are not accepted as `ipv4_address`, they should be
-resolved first using ``socket.getaddrinfo()``.
+1-65535. Note the domain names are not accepted as *ipv4_address*, they should be
+resolved first using `usocket.getaddrinfo()`.
 
 Functions
 ---------
 
-.. function:: socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_TCP)
+.. function:: socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP)
 
    Create a new socket using the given address family, socket type and protocol number.
 
-.. function:: socket.getaddrinfo(host, port)
+.. function:: getaddrinfo(host, port)
 
    Translate the host/port argument into a sequence of 5-tuples that contain all the 
    necessary arguments for creating a socket connected to that service. The list of 
@@ -57,11 +57,11 @@ Functions
    .. admonition:: Difference to CPython
       :class: attention
 
-      CPython raises a ``socket.gaierror`` exception (OSError subclass) in case
+      CPython raises a ``socket.gaierror`` exception (`OSError` subclass) in case
       of error in this function. MicroPython doesn't have ``socket.gaierror``
-      and raises OSError directly. Note that error numbers of ``getaddrinfo()``
+      and raises OSError directly. Note that error numbers of `getaddrinfo()`
       form a separate namespace and may not match error numbers from
-      ``uerrno`` module. To distinguish ``getaddrinfo()`` errors, they are
+      `uerrno` module. To distinguish `getaddrinfo()` errors, they are
       represented by negative numbers, whereas standard system errors are
       positive numbers (error numbers are accessible using ``e.args[0]`` property
       from an exception object). The use of negative values is a provisional
@@ -70,32 +70,34 @@ Functions
 Constants
 ---------
 
-.. data:: socket.AF_INET
-          socket.AF_INET6
+.. data:: AF_INET
+          AF_INET6
 
    Address family types. Availability depends on a particular board.
 
-.. data:: socket.SOCK_STREAM
-          socket.SOCK_DGRAM
+.. data:: SOCK_STREAM
+          SOCK_DGRAM
 
    Socket types.
 
-.. data:: socket.IPPROTO_UDP
-          socket.IPPROTO_TCP
+.. data:: IPPROTO_UDP
+          IPPROTO_TCP
 
    IP protocol numbers.
 
-.. data:: socket.SOL_*
+.. data:: usocket.SOL_*
 
-   Socket option levels (an argument to ``setsockopt()``). The exact inventory depends on a board.
+   Socket option levels (an argument to `setsockopt()`). The exact
+   inventory depends on a MicroPython port.
 
-.. data:: socket.SO_*
+.. data:: usocket.SO_*
 
-   Socket options (an argument to ``setsockopt()``). The exact inventory depends on a board.
+   Socket options (an argument to `setsockopt()`). The exact
+   inventory depends on a MicroPython port.
 
 Constants specific to WiPy:
 
-.. data:: socket.IPPROTO_SEC
+.. data:: IPPROTO_SEC
 
     Special protocol value to create SSL-compatible socket.
 
@@ -105,21 +107,22 @@ class socket
 Methods
 -------
 
-.. method:: socket.close
+.. method:: socket.close()
 
-   Mark the socket closed. Once that happens, all future operations on the socket 
-   object will fail. The remote end will receive no more data (after queued data is flushed).
+   Mark the socket closed and release all resources. Once that happens, all future operations
+   on the socket object will fail. The remote end will receive EOF indication if
+   supported by protocol.
 
    Sockets are automatically closed when they are garbage-collected, but it is recommended 
-   to close() them explicitly, or to use a with statement around them.
+   to `close()` them explicitly as soon you finished working with them.
 
 .. method:: socket.bind(address)
 
-   Bind the socket to address. The socket must not already be bound.
+   Bind the socket to *address*. The socket must not already be bound.
 
 .. method:: socket.listen([backlog])
 
-   Enable a server to accept connections. If backlog is specified, it must be at least 0 
+   Enable a server to accept connections. If *backlog* is specified, it must be at least 0
    (if it's lower, it will be set to 0); and specifies the number of unaccepted connections
    that the system will allow before refusing new connections. If not specified, a default
    reasonable value is chosen.
@@ -133,7 +136,7 @@ Methods
 
 .. method:: socket.connect(address)
 
-   Connect to a remote socket at address.
+   Connect to a remote socket at *address*.
 
 .. method:: socket.send(bytes)
 
@@ -144,11 +147,11 @@ Methods
 .. method:: socket.sendall(bytes)
 
    Send all data to the socket. The socket must be connected to a remote socket.
-   Unlike ``send()``, this method will try to send all of data, by sending data
+   Unlike `send()`, this method will try to send all of data, by sending data
    chunk by chunk consecutively.
 
    The behavior of this method on non-blocking sockets is undefined. Due to this,
-   on MicroPython, it's recommended to use ``write()`` method instead, which
+   on MicroPython, it's recommended to use `write()` method instead, which
    has the same "no short writes" policy for blocking sockets, and will return
    number of bytes sent on non-blocking sockets.
 
@@ -160,33 +163,33 @@ Methods
 .. method:: socket.sendto(bytes, address)
 
    Send data to the socket. The socket should not be connected to a remote socket, since the
-   destination socket is specified by `address`.
+   destination socket is specified by *address*.
 
 .. method:: socket.recvfrom(bufsize)
 
-  Receive data from the socket. The return value is a pair (bytes, address) where bytes is a
-  bytes object representing the data received and address is the address of the socket sending
+  Receive data from the socket. The return value is a pair *(bytes, address)* where *bytes* is a
+  bytes object representing the data received and *address* is the address of the socket sending
   the data.
 
 .. method:: socket.setsockopt(level, optname, value)
 
    Set the value of the given socket option. The needed symbolic constants are defined in the
-   socket module (SO_* etc.). The value can be an integer or a bytes-like object representing
+   socket module (SO_* etc.). The *value* can be an integer or a bytes-like object representing
    a buffer.
 
 .. method:: socket.settimeout(value)
 
    Set a timeout on blocking socket operations. The value argument can be a nonnegative floating
    point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations
-   will raise an ``OSError`` exception if the timeout period value has elapsed before the operation has
+   will raise an `OSError` exception if the timeout period value has elapsed before the operation has
    completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket
    is put in blocking mode.
 
    .. admonition:: Difference to CPython
       :class: attention
 
       CPython raises a ``socket.timeout`` exception in case of timeout,
-      which is an ``OSError`` subclass. MicroPython raises an OSError directly
+      which is an `OSError` subclass. MicroPython raises an OSError directly
       instead. If you use ``except OSError:`` to catch the exception,
       your code will work both in MicroPython and CPython.
 
@@ -195,7 +198,7 @@ Methods
    Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking,
    else to blocking mode.
 
-   This method is a shorthand for certain ``settimeout()`` calls:
+   This method is a shorthand for certain `settimeout()` calls:
 
    * ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)``
    * ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0)``
@@ -204,12 +207,12 @@ Methods
 
    Return a file object associated with the socket. The exact returned type depends on the arguments
    given to makefile(). The support is limited to binary modes only ('rb', 'wb', and 'rwb').
-   CPython's arguments: ``encoding``, ``errors`` and ``newline`` are not supported.
+   CPython's arguments: *encoding*, *errors* and *newline* are not supported.
 
    .. admonition:: Difference to CPython
       :class: attention
 
-      As MicroPython doesn't support buffered streams, values of ``buffering``
+      As MicroPython doesn't support buffered streams, values of *buffering*
       parameter is ignored and treated as if it was 0 (unbuffered).
 
    .. admonition:: Difference to CPython
@@ -220,19 +223,19 @@ Methods
 
 .. method:: socket.read([size])
 
-   Read up to size bytes from the socket. Return a bytes object. If ``size`` is not given, it
-   reads all data available from the socket until ``EOF``; as such the method will not return until
+   Read up to size bytes from the socket. Return a bytes object. If *size* is not given, it
+   reads all data available from the socket until EOF; as such the method will not return until
    the socket is closed. This function tries to read as much data as
    requested (no "short reads"). This may be not possible with
    non-blocking socket though, and then less data will be returned.
 
 .. method:: socket.readinto(buf[, nbytes])
 
-   Read bytes into the ``buf``.  If ``nbytes`` is specified then read at most
-   that many bytes.  Otherwise, read at most ``len(buf)`` bytes. Just as
-   ``read()``, this method follows "no short reads" policy.
+   Read bytes into the *buf*.  If *nbytes* is specified then read at most
+   that many bytes.  Otherwise, read at most *len(buf)* bytes. Just as
+   `read()`, this method follows "no short reads" policy.
 
-   Return value: number of bytes read and stored into ``buf``.
+   Return value: number of bytes read and stored into *buf*.
 
 .. method:: socket.readline()
 
@@ -245,6 +248,6 @@ Methods
    Write the buffer of bytes to the socket. This function will try to
    write all data to a socket (no "short writes"). This may be not possible
    with a non-blocking socket though, and returned value will be less than
-   the length of ``buf``.
+   the length of *buf*.
 
    Return value: number of bytes written.
