Add useful docstrings

[tjguk]

(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:

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>

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.

[yeyeto2788]

Hello guys! if you want I can add the doc strings class by class making a PR.

One important thing IMHO is to decide what type of doc string to use, here I have looked for the most used ones:

• reStructuredText
• Epydoc
• And the one that I've been using on my projects. It is the Google Python Style Guide (Helpful but Deprecated)

Also as far as I know Sphinx's (as @tjguk commented) can be used to auto generate reStructuredText Doc Strings.

I would also recommend to set this code style on the Contributing section of the Wiki

Regards.

[martinohanlon]

@yeyeto2788 I have already started to add doc strings into the guizero class using reStructuredText. See ListBox for an example https://github.com/lawsie/guizero/blob/master/guizero/ListBox.py

Any help in adding additional doc strings would be greatly received. :)

[tjguk]

Are you running a docstring branch / PR or just docstring-ing as you go along?

[martinohanlon]

As I go. If I change a class I tend to take the opportunity to document it.

[tjguk]

Makes sense. I hope to start using guizero for some sessions I'm running with a few Y8s. If I do I'll try to get them to contribute docstrings as part of the learning experience

[yeyeto2788]

Hello guys! Sorry for the late reply.

@martinohanlon I will then use reStructuredText

@tjguk I will start from tomorrow and I thought about making a branch for docstring and after reviewing the PR can be merge to master.

Let me know if this approach is ok for you guys.

Regards

[tjguk]

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

[martinohanlon]

Closing - the vast majority of doc strings are included, those that arent can be added as and when needed.