Tried Ruby (or, "what Python *really* needs" or "perldoc!")

[Paul Boddie]

john_sips_tea at yahoo.com wrote:

[Quoting Aaron Watters - *the* Aaron Watters?!]

> > And the patch procedure you described requires
> > a higher degree of motivation (and free time) than
> > most potential contributors might have on offer, imo.

The patch procedure described seemed to involve mailing python-dev,
which I thought was not the accepted practice. Even making patch
descriptions in SourceForge won't apparently get patches straight into
Python, although there may be fewer restrictions on submitting
documentation patches.

> Another option is to simply email the author/maintainer
> for a given module your modifications to their module.
>
> cd ~/dev/python/modified_modules
> cp /path/to/module_needs_docs.py .
> vim ./module_needs_docs.py   # add docs

True, but I'm not convinced this is going to work when the modules are
in the standard library. Anyway, there were going to be some
improvements to the processes, last time I looked, and various editable
resources did spring up to meet the need for documentation edits - none
of them official as far as I know, though.

Paul

P.S. On the documentation-from-sources question, I've had some success
with epydoc. Some documentation systems (even those for
statically-typed languages) have you describe parameters in
mind-numbing detail, but all I would expect from a documentation tool
is that it highlight mentions of the parameter names in my docstrings.
Having some understanding of the nasty issues around deducing types, I
wouldn't expect a tool to fill in the gaps about parameter types: good
documentation for dynamic languages like Python should be able to
describe what kind of objects should be passed in, and type deduction
could actually give quite the wrong impression about acceptable
arguments to functions, although interface descriptions could be
helpful.