[Tutor] Code documentation

[Alan Gauld]

"Carlos Daniel Ruvalcaba Valenzuela" <clsdaniel at 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/