search

open-iscsi / rtslib-fb

Python library for configuring the Linux kernel-based multiprotocol SCSI target (LIO)
Apache License 2.0
73 stars 90 forks source link

add return types to epydoc docstrings #11

Open JonnyJD opened 12 years ago

JonnyJD commented 12 years ago

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@d95ecc6ecd3eab4c0803364ec225829bdf5f20bb) additions.

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

JonnyJD commented 12 years ago

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 commented 12 years ago

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 commented 12 years ago

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 commented 10 years ago

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 commented 10 years ago

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.