"Carlos Daniel Ruvalcaba Valenzuela" <clsdan...@gmail.com> wrote
which approach should I take on documentation (API docs) for a
python
library I have been working on, there is currently code docstrings,
docstrings are the minimum since they show up on help()
docstrings with some markup (epydoc, etc), or external programs such
as Sphinx (reStructuredText markup).
Personally I never use these. I use help() in the first instance and
failing that go to the html module docs.
In your experience which way is the best or what
advantages/disadvantages do you see (experienced) with each approach
that you are familiar.
Fancy markup is a wasted luxury so far as I am concerned.
The most important documentation is the signature of the function
ie the bit that looks like:
int(x[, base]) -> integer
Provided the function and params have descriptive names
then 90% of the time thats all I need!
--
Alan G
Author of the Learn to Program web site
http://www.alan-g.me.uk/
_______________________________________________
Tutor maillist - Tutor@python.org
http://mail.python.org/mailman/listinfo/tutor
