Add useful docstrings

(Not unrelated to #38)

At present if you help() the package itself or any of its components, you basically get the whole Tk stack and no overview. In general, in Python, encourage exploration via introspection (help, dir, inspect etc.). And tools like IPython and the built-in docs browser support that to a considerable extent.

Here’s an example from my own networkzero:

<dump> Help on module networkzero.discovery in networkzero:

NAME networkzero.discovery - Advertise and collect advertisements of network services

DESCRIPTION The discovery module offers:

    * A UDP broadcast socket which:

      - Listens for and keeps track of service adverts from this and other
        machines & processes
      - Broadcasts services advertised by this process

    * A ZeroMQ socket which allow any process on this machine to
      communicate with its broadcast socket

In other words, we have a beacon which listens to instructions
from processes on this machine while sending out and listening
to adverts broadcast to/from all machines on the network.

The beacon is started automatically in a daemon thread when the first
attempt is made to advertise or discover. If another process already
has a beacon running (ie if this beacon can't bind to its port) this
beacon thread will shut down with no further action.

The module-level functions to advertise and discover will open a connection
to a ZeroMQ socket on this machine (which might be hosted by this or by another
process) and will use this socket to send commands to the beacon thread which
will update or return its internal list of advertised services.

As an additional convenience, the :func:`advertise` function will, if given no
specific address, generate a suitable ip:port pair by interrogating the system.
This functionality is actually in :func:`networkzero.address` (qv).

FUNCTIONS advertise(name, address=None, fail_if_exists=False, ttl_s=20) Advertise a name at an address

    Start to advertise service `name` at address `address`. If
    the address is not supplied, one is constructed and this is
    returned by the function. ie this is a typical use::

        address = nw0.advertise("myservice")

    :param name: any text
    :param address: either "ip:port" or None
    :param fail_if_exists: fail if this name is already registered?
    :param ttl_s: the advert will persist for this many seconds other beacons
    :returns: the address given or constructed</dump>

</dump>

In this case I’m using Sphinx’s auto-doc features to combine this help() text with some other narrative in the documentation, but I see it as very key that people be able to help(mymodule) and get more than the barebones alpha-orderd breakdown of what’s in it.

[martinohanlon]

Fyi - I am slowly adding doc strings to guizero, I do them as an when I make a significant change to a class.

[tjguk]

For my part, go ahead with whatever works. Insofar as I end up contributing, I’ll follow along with whatever’s acceptable