docs: Cleanup and update some docs.

docs/library/cmath.rst

@@ -1,5 +1,5 @@
-:mod:`cmath` --- mathematical functions for complex numbers
-===========================================================
+:mod:`cmath` -- mathematical functions for complex numbers
+==========================================================
 
 .. module:: cmath
    :synopsis: mathematical functions for complex numbers
@@ -7,7 +7,6 @@
 The ``cmath`` module provides some basic mathematical funtions for
 working with complex numbers.
 
-
 Functions
 ---------
 
@@ -47,7 +46,6 @@ Functions
 
    Return the square-root of ``z``.
 
-
 Constants
 ---------
 

docs/library/gc.rst

@@ -1,5 +1,5 @@
-:mod:`gc` --- control the garbage collector
-===========================================
+:mod:`gc` -- control the garbage collector
+==========================================
 
 .. module:: gc
    :synopsis: control the garbage collector

docs/library/math.rst

@@ -1,5 +1,5 @@
-:mod:`math` --- mathematical functions
-======================================
+:mod:`math` -- mathematical functions
+=====================================
 
 .. module:: math
    :synopsis: mathematical functions
@@ -7,45 +7,58 @@
 The ``math`` module provides some basic mathematical funtions for
 working with floating-point numbers.
 
+*Note:* On the pyboard, floating-point numbers have 32-bit precision.
 
 Functions
 ---------
 
 .. function:: acos(x)
 
+   Return the inverse cosine of ``x``.
 
 .. function:: acosh(x)
 
+   Return the inverse hyperbolic cosine of ``x``.
 
 .. function:: asin(x)
 
+   Return the inverse sine of ``x``.
 
 .. function:: asinh(x)
 
+   Return the inverse hyperbolic sine of ``x``.
 
 .. function:: atan(x)
 
+   Return the inverse tangent of ``x``.
 
 .. function:: atan2(y, x)
 
+   Return the principal value of the inverse tangent of ``y/x``.
 
 .. function:: atanh(x)
 
+   Return the inverse hyperbolic tangent of ``x``.
 
 .. function:: ceil(x)
 
+   Return an integer, being ``x`` rounded towards positive infinity.
 
 .. function:: copysign(x, y)
 
+   Return ``x`` with the sign of ``y``.
 
 .. function:: cos(x)
 
+   Return the cosine of ``x``.
 
 .. function:: cosh(x)
 
+   Return the hyperbolic cosine of ``x``.
 
 .. function:: degrees(x)
 
+   Return radians ``x`` converted to degrees.
 
 .. function:: erf(x)
 
@@ -57,18 +70,23 @@ Functions
 
 .. function:: exp(x)
 
+   Return the exponential of ``x``.
 
 .. function:: expm1(x)
 
+   Return ``exp(x) - 1``.
 
 .. function:: fabs(x)
 
+   Return the absolute value of ``x``.
 
 .. function:: floor(x)
 
+   Return an integer, being ``x`` rounded towards negative infinity.
 
 .. function:: fmod(x, y)
 
+   Return the remainder of ``x/y``.
 
 .. function:: frexp(x)
 
@@ -80,31 +98,40 @@ Functions
 
 .. function:: isfinite(x)
 
+   Return ``True`` if ``x`` is finite.
 
 .. function:: isinf(x)
 
+   Return ``True`` if ``x`` is infinite.
 
 .. function:: isnan(x)
 
+   Return ``True`` if ``x`` is not-a-number
 
 .. function:: ldexp(x, exp)
 
+   Return ``x * (2**exp)``.
 
 .. function:: lgamma(x)
 
-   return the natural logarithm of the gamma function of ``x``.
+   Return the natural logarithm of the gamma function of ``x``.
 
 .. function:: log(x)
 
+   Return the natural logarithm of ``x``.
 
 .. function:: log10(x)
 
+   Return the base-10 logarithm of ``x``.
 
 .. function:: log2(x)
 
+   Return the base-2 logarithm of ``x``.
 
 .. function:: modf(x)
 
+   Return a tuple of two floats, being the fractional and integral parts of
+   ``x``.  Both return values have the same sign as ``x``.
 
 .. function:: pow(x, y)
 
@@ -112,26 +139,31 @@ Functions
 
 .. function:: radians(x)
 
+   Return degrees ``x`` converted to radians.
 
 .. function:: sin(x)
 
+   Return the sine of ``x``.
 
 .. function:: sinh(x)
 
+   Return the hyperbolic sine of ``x``.
 
 .. function:: sqrt(x)
 
-   Returns the square root of ``x``.
+   Return the square root of ``x``.
 
 .. function:: tan(x)
 
+   Return the tangent of ``x``.
 
 .. function:: tanh(x)
 
+   Return the hyperbolic tangent of ``x``.
 
 .. function:: trunc(x)
 
-
+   Return an integer, being ``x`` rounded towards 0.
 
 Constants
 ---------

docs/library/os.rst

@@ -1,21 +1,24 @@
-:mod:`os` --- basic "operating system" services
-===============================================
+:mod:`os` -- basic "operating system" services
+==============================================
 
 .. module:: os
    :synopsis: basic "operating system" services
 
 The ``os`` module contains functions for filesystem access and ``urandom``.
 
-The filesystem has ``/`` as the root directory, and the available physical
-drives are accessible from here.  They are currently:
+Pyboard specifics
+-----------------
 
-    /flash      -- the internal flash filesystem
-    /sd         -- the SD card (if it exists)
+The filesystem on the pyboard has ``/`` as the root directory and the
+available physical drives are accessible from here.  They are currently:
+
+    ``/flash``      -- the internal flash filesystem
+
+    ``/sd``         -- the SD card (if it exists)
 
 On boot up, the current directory is ``/flash`` if no SD card is inserted,
 otherwise it is ``/sd``.
 
-
 Functions
 ---------
 
@@ -56,7 +59,6 @@ Functions
    Return a bytes object with n random bytes, generated by the hardware
    random number generator.
 
-
 Constants
 ---------
 

docs/library/pyb.ADC.rst

@@ -1,5 +1,5 @@
-class ADC =-- analog to digital conversion: read analog values on a pin
-=======================================================================
+class ADC -- analog to digital conversion: read analog values on a pin
+======================================================================
 
 Usage::
 

docs/library/pyb.Accel.rst

@@ -1,5 +1,5 @@
-class Accel --- accelerometer control
-=====================================
+class Accel -- accelerometer control
+====================================
 
 Accel is an object that controls the accelerometer.  Example usage::
 

docs/library/pyb.CAN.rst

@@ -1,5 +1,5 @@
-class CAN --- controller area network communication bus
-=======================================================
+class CAN -- controller area network communication bus
+======================================================
 
 CAN implements the standard CAN communications protocol.  At
 the physical level it consists of 2 lines: RX and TX.  Note that

docs/library/pyb.DAC.rst

@@ -1,5 +1,5 @@
-class DAC --- digital to analog conversion
-==========================================
+class DAC -- digital to analog conversion
+=========================================
 
 The DAC is used to output analog values (a specific voltage) on pin X5 or pin X6.
 The voltage will be between 0 and 3.3V.

docs/library/pyb.ExtInt.rst

@@ -1,5 +1,5 @@
-class ExtInt --- configure I/O pins to interrupt on external events
-===================================================================
+class ExtInt -- configure I/O pins to interrupt on external events
+==================================================================
 
 There are a total of 22 interrupt lines. 16 of these can come from GPIO pins
 and the remaining 6 are from internal sources.

docs/library/pyb.I2C.rst

@@ -1,5 +1,5 @@
-class I2C --- a two-wire serial protocol
-========================================
+class I2C -- a two-wire serial protocol
+=======================================
 
 I2C is a two-wire protocol for communicating between devices.  At the physical
 level it consists of 2 wires: SCL and SDA, the clock and data lines respectively.

docs/library/pyb.LCD.rst

@@ -1,5 +1,5 @@
-class LCD --- LCD control for the LCD touch-sensor pyskin
-=========================================================
+class LCD -- LCD control for the LCD touch-sensor pyskin
+========================================================
 
 The LCD class is used to control the LCD on the LCD touch-sensor pyskin,
 LCD32MKv1.0.  The LCD is a 128x32 pixel monochrome screen, part NHD-C12832A1Z.

docs/library/pyb.LED.rst

@@ -1,5 +1,5 @@
-class LED --- LED object
-========================
+class LED -- LED object
+=======================
 
 The LED object controls an individual LED (Light Emitting Diode).
 

docs/library/pyb.Pin.rst

@@ -1,5 +1,5 @@
-class Pin --- control I/O pins
-==============================
+class Pin -- control I/O pins
+=============================
 
 A pin is the basic object to control I/O pins.  It has methods to set
 the mode of the pin (input, output, etc) and methods to get and set the
@@ -206,3 +206,56 @@ Constants
 .. data:: Pin.PULL_UP
 
    enable the pull-up resistor on the pin
+
+
+class PinAF -- Pin Alternate Functions
+======================================
+
+A Pin represents a physical pin on the microcprocessor. Each pin
+can have a variety of functions (GPIO, I2C SDA, etc). Each PinAF
+object represents a particular function for a pin.
+
+Usage Model::
+
+    x3 = pyb.Pin.board.X3
+    x3_af = x3.af_list()
+
+x3_af will now contain an array of PinAF objects which are availble on
+pin X3.
+
+For the pyboard, x3_af would contain:
+    [Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2]
+
+Normally, each peripheral would configure the af automatically, but sometimes
+the same function is available on multiple pins, and having more control
+is desired.
+
+To configure X3 to expose TIM2_CH3, you could use::
+
+   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=pyb.Pin.AF1_TIM2)
+
+or::
+
+   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1)
+
+
+Methods
+-------
+
+.. method:: pinaf.__str__()
+
+   Return a string describing the alternate function.
+
+.. method:: pinaf.index()
+
+   Return the alternate function index.
+
+.. method:: pinaf.name()
+
+   Return the name of the alternate function.
+
+.. method:: pinaf.reg()
+
+   Return the base register associated with the peripheral assigned to this
+   alternate function. For example, if the alternate function were TIM2_CH3
+   this would return stm.TIM2

docs/library/pyb.PinAF.rst

@@ -1,51 +0,0 @@
-class PinAF --- Pin Alternate Functions
-=======================================
-
-A Pin represents a physical pin on the microcprocessor. Each pin
-can have a variety of functions (GPIO, I2C SDA, etc). Each PinAF
-object represents a particular function for a pin.
-
-Usage Model::
-
-    x3 = pyb.Pin.board.X3
-    x3_af = x3.af_list()
-
-x3_af will now contain an array of PinAF objects which are availble on
-pin X3.
-
-For the pyboard, x3_af would contain:
-    [Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2]
-
-Normally, each peripheral would configure the af automatically, but sometimes
-the same function is available on multiple pins, and having more control
-is desired.
-
-To configure X3 to expose TIM2_CH3, you could use::
-
-   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=pyb.Pin.AF1_TIM2)
-
-or::
-
-   pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1)
-
-
-Methods
--------
-
-.. method:: pinaf.__str__()
-
-   Return a string describing the alternate function.
-
-.. method:: pinaf.index()
-
-   Return the alternate function index.
-
-.. method:: pinaf.name()
-
-   Return the name of the alternate function.
-
-.. method:: pinaf.reg()
-
-   Return the base register associated with the peripheral assigned to this
-   alternate function. For example, if the alternate function were TIM2_CH3
-   this would return stm.TIM2

docs/library/pyb.RTC.rst

@@ -1,5 +1,5 @@
-class RTC --- real time clock
-=============================
+class RTC -- real time clock
+============================
 
 The RTC is and independent clock that keeps track of the date
 and time.

docs/library/pyb.SPI.rst

@@ -1,5 +1,5 @@
-class SPI --- a master-driven serial protocol
-=============================================
+class SPI -- a master-driven serial protocol
+============================================
 
 SPI is a serial protocol that is driven by a master.  At the physical level
 there are 3 lines: SCK, MOSI, MISO.

docs/library/pyb.Servo.rst

@@ -1,5 +1,5 @@
-class Servo --- 3-wire hobby servo driver
-=========================================
+class Servo -- 3-wire hobby servo driver
+========================================
 
 Servo controls standard hobby servos with 3-wires (ground, power, signal).
 

docs/library/pyb.Switch.rst

@@ -1,5 +1,5 @@
-class Switch --- switch object
-==============================
+class Switch -- switch object
+=============================
 
 A Switch object is used to control a push-button switch.
 

docs/library/pyb.Timer.rst

@@ -1,5 +1,5 @@
-class Timer --- control internal timers
-=======================================
+class Timer -- control internal timers
+======================================
 
 Timers can be used for a great variety of tasks.  At the moment, only
 the simplest case is implemented: that of calling a function periodically.

docs/library/pyb.UART.rst

@@ -1,5 +1,5 @@
-class UART --- duplex serial communication bus
-==============================================
+class UART -- duplex serial communication bus
+=============================================
 
 UART implements the standard UART/USART duplex serial communications protocol.  At
 the physical level it consists of 2 lines: RX and TX.  The unit of communication
@@ -36,6 +36,8 @@ To check if there is anything to be read, use::
 
     uart.any()               # returns True if any characters waiting
 
+*Note:* The stream functions ``read``, ``write`` etc Are new in Micro Python since v1.3.4.
+Earlier versions use ``uart.send`` and ``uart.recv``.
 
 Constructors
 ------------
@@ -56,7 +58,6 @@ Constructors
      - ``UART(3)`` is on ``YB``: ``(TX, RX) = (Y9, Y10) = (PB10, PB11)``
      - ``UART(2)`` is on: ``(TX, RX) = (X3, X4) = (PA2, PA3)``
 
-
 Methods
 -------
 
@@ -87,13 +88,18 @@ Methods
 
    Read characters.  If ``nbytes`` is specified then read at most that many bytes.
 
-   *Note:* for 9 bit characters each character takes 2 bytes, ``nbytes`` must be even,
-   and the number of characters is ``nbytes/2``.
+   *Note:* for 9 bit characters each character takes two bytes, ``nbytes`` must
+   be even, and the number of characters is ``nbytes/2``.
+
+   Return value: a bytes object containing the bytes read in.  Returns ``b''``
+   on timeout.
 
 .. method:: uart.readall()
 
    Read as much data as possible.
 
+   Return value: a bytes object.
+
 .. method:: uart.readchar()
 
    Receive a single character on the bus.
@@ -102,12 +108,25 @@ Methods
 
 .. method:: uart.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.
+
+   Return value: number of bytes read and stored into ``buf``.
 
 .. method:: uart.readline()
 
+   Read a line, ending in a newline character.
+
+   Return value: the line read.
 
 .. method:: uart.write(buf)
 
+   Write the buffer of bytes to the bus.  If characters are 7 or 8 bits wide
+   then each byte is one character.  If characters are 9 bits wide then two
+   bytes are used for each character (little endian), and ``buf`` must contain
+   an even number of bytes.
+
+   Return value: number of bytes written.
 
 .. method:: uart.writechar(char)
 

docs/library/pyb.USB_VCP.rst

@@ -1,5 +1,5 @@
-class USB_VCP --- USB virtual comm port
-=======================================
+class USB_VCP -- USB virtual comm port
+======================================
 
 The USB_VCP class allows creation of an object representing the USB
 virtual comm port.  It can be used to read and write data over USB to

docs/library/pyb.rst

@@ -160,7 +160,6 @@ Classes
    pyb.I2C.rst
    pyb.LCD.rst
    pyb.LED.rst
-   pyb.PinAF.rst
    pyb.Pin.rst
    pyb.RTC.rst
    pyb.Servo.rst

docs/library/select.rst

@@ -1,37 +1,52 @@
-:mod:`select` --- Provides select function to wait for events on a stream
-=========================================================================
+:mod:`select` -- Provides select function to wait for events on a stream
+========================================================================
 
 .. module:: select
    :synopsis: Provides select function to wait for events on a stream
 
 This module provides the select function.
 
+Pyboard specifics
+-----------------
+
+Polling is an efficient way of waiting for read/write activity on multiple
+objects.  Current objects that support polling are: :class:`pyb.UART`,
+:class:`pyb.USB_VCP`.
 
 Functions
 ---------
 
 .. function:: poll()
 
+   Create an instance of the Poll class.
 
 .. function:: select(rlist, wlist, xlist[, timeout])
 
+   Wait for activity on a set of objects.
 
-class Poll
-----------
+.. _class: Poll
 
+class ``Poll``
+--------------
 
 Methods
--------
-
-.. method:: poll.modify(obj, eventmask)
-
-
-.. method:: poll.poll([timeout])
-
-   Timeout is in milliseconds.
+~~~~~~~
 
 .. method:: poll.register(obj[, eventmask])
 
+   Register ``obj`` for polling.  ``eventmask`` is 1 for read, 2 for
+   write, 3 for read-write.
 
 .. method:: poll.unregister(obj)
 
+   Unregister ``obj`` from polling.
+
+.. method:: poll.modify(obj, eventmask)
+
+   Modify the ``eventmask`` for ``obj``.
+
+.. method:: poll.poll([timeout])
+
+   Wait for one of the registered objects to become ready.
+
+   Timeout is in milliseconds.

docs/library/sys.rst

@@ -1,11 +1,9 @@
-:mod:`sys` --- system specific functions
-========================================
+:mod:`sys` -- system specific functions
+=======================================
 
 .. module:: sys
    :synopsis: system specific functions
 
-
-
 Functions
 ---------
 
@@ -14,7 +12,6 @@ Functions
    Raise a ``SystemExit`` exception.  If an argument is given, it is the
    value given to ``SystemExit``.
 
-
 Constants
 ---------
 

docs/library/time.rst

@@ -1,5 +1,5 @@
-:mod:`time` --- time related functions
-======================================
+:mod:`time` -- time related functions
+=====================================
 
 .. module:: time
    :synopsis: time related functions
@@ -7,7 +7,6 @@
 The ``time`` module provides functions for getting the current time and date,
 and for sleeping.
 
-
 Functions
 ---------
 
@@ -16,14 +15,15 @@ Functions
    Convert a time expressed in seconds since Jan 1, 2000 into an 8-tuple which
    contains: (year, month, mday, hour, minute, second, weekday, yearday)
    If secs is not provided or None, then the current time from the RTC is used.
-   year includes the century (for example 2014)
-   month   is 1-12
-   mday    is 1-31
-   hour    is 0-23
-   minute  is 0-59
-   second  is 0-59
-   weekday is 0-6 for Mon-Sun.
-   yearday is 1-366
+   year includes the century (for example 2014).
+
+   * month   is 1-12
+   * mday    is 1-31
+   * hour    is 0-23
+   * minute  is 0-59
+   * second  is 0-59
+   * weekday is 0-6 for Mon-Sun
+   * yearday is 1-366
 
 .. function:: mktime()
 

docs/library/uheapq.rst

@@ -1,5 +1,5 @@
-:mod:`uheapq` --- heap queue algorithm
-======================================
+:mod:`uheapq` -- heap queue algorithm
+=====================================
 
 .. module:: uheapq
    :synopsis: heap queue algorithm

docs/library/ujson.rst

@@ -1,5 +1,5 @@
-:mod:`ujson` --- JSON encoding and decoding
-===========================================
+:mod:`ujson` -- JSON encoding and decoding
+==========================================
 
 .. module:: ujson
    :synopsis: JSON encoding and decoding

docs/library/usocket.rst

@@ -1,12 +1,11 @@
-:mod:`usocket` --- socket module
-================================
+:mod:`usocket` -- socket module
+===============================
 
 .. module:: usocket
    :synopsis: socket module
 
 Socket functionality.
 
-
 Functions
 ---------