docstring style modifications

[GoogleCodeExporter]

The current pyglet documentation style is ReST, but there are epydoc specific 
notations that should be checked.

The doc build process can convert automatically some things, but there are some 
things to be done manually:

* Add API internal links using reference tags (:class: :meth: :attr: :func:)

* Refactor the :Ivariables: blocks, most of them should be a :parameters: block 
in the constructor, and the rest as attribute docstrings. 

Original issue reported on code.google.com by tx...@nabla.net on 14 Dec 2013 at 4:17

[GoogleCodeExporter]

I believe the best is to have all in one syntax, independently of whether the 
build can convert them or not. When someone is reading the code, she normally 
uses the docs written in the source code to help understanding the code. Having 
two different syntaxes does not help at all.

I also think there is some code written specifically to improve the epydoc 
documentation that should go away, such as 
https://code.google.com/p/pyglet/source/browse/pyglet/app/base.py#347

I have to admit I have never seem an "if" for documentation... a quick search 
finds at least 14 examples.

However, I don't know how we change this since

1. there are too much docs to change;
2. there are forks that would have to fix tons of merge conflicts if we change 
these "automatically".

Original comment by jorgecar...@gmail.com on 17 Dec 2013 at 7:15

[GoogleCodeExporter]

The idea is to use a unique style: take the format in which the 
documentation is already written, and change only what is necessary. 
There are examples of other libraries such as numpy, which also use an 
extended ReST sintax. Although you could use pure ReST and write a 
:param: list, please don't: the source is much more readable as it is now.

In this issue I do not want to touch anything out of the docstrings, so 
the merge conflicts should be easy to resolve. The "if _is_epydoc" 
thingy and other doc related details are for another issue.

Check everything by hand is a job that will take time, but I've already 
started, and in my opinion the documentation is much more useful with 
internal links.

Original comment by tx...@nabla.net on 18 Dec 2013 at 4:39