add return types to epydoc docstrings

[JonnyJD]

Working on the session API I realized, that most properties and functions don't list a return type.
The format is @return: description and @rtype: type for functions and @type: type for properties (and instance variables). This is especially helpful because we can even link the types: L{NodeACL}.

epydoc is already used and there is also an old documentation online. There is a lot of epydoc-specific parameter documentation in the docstrings of functions, but somehow return types are missing.

I documented my session branch (JonnyJD/rtslib-fb@d95ecc6) additions.

I note that we don't really have to document private functions and variables this way.

[JonnyJD]

Again, this changes a lot of code and could possibly disrupt merges from upstream.

On the other hand: upstream should better document their return types..

[agrover]

Sounds good. After thinking about it this weekend I'm less worried about sticking close to upstream. Up-to-date API docs would be very nice to have,

[JonnyJD]

First step for having up-to-date docs: using the documentation of the latest code.

I created JonnyJD.github.com/rtslib-fb/, including docs. This is generated directly from your master with this Makefile.

[agrover]

it's been a while. I have a little free time, should we still try to get this done or close this and move on?

[JonnyJD]

Unfortunately I don't have much free time at the moment.

I am now using sphinx for new Python projects.
Either way, I still think we should have (up-to-date) rtslib-fb API docs online. That would be the first step. Regardless of having return types documented or not. To just keep using epydocs is fine.

I pushed latest git to http://jonnyjd.github.io/rtslib-fb/doc/latest/ (with my Makefile) but there is possibly a better place to host this. Maybe agrover/rtslib-fb or something completely different.
The index http://jonnyjd.github.io/rtslib-fb/ is not yet updated though.