On Mon, Feb 02, 2009 at 12:51:54AM +0900, Luiz Vitor Martinez Cardoso wrote:
> People,
> 
> What the Ruby community think about developing a better documentation system.
> Something like Python Documentation?
> 
> We need to improve de interface and the content, we need to be able to help
> ruby 1.9 grow and grow!
> 
> What your opinion?

I've been playing with python documentation tools recently, as I've been
working on a new python library at work.

I like docstrings.  I like being able to type "help(foo)" in python and
get help on the foo method.

I don't like docstrings.  They don't let you write documentation for
variables -- only modules, classes, and methods.  We're using epydoc,
and it has a special syntax for elements of the program that python
doesn't handle.

I like restructed text.  It means that the documentation is readable in
a text editor, much like having wiki formatting inside my code.

I don't like restructed text.  The syntax and rules are complex, and
sometimes it's hard to remember what sort of syntax I'm supposed to use.
If I get it wrong, there's no compile error; it just doesn't show up
correctly in the documentation.

I know these things aren't quite what you were getting at, but I
thought I'd chime in anyway.

Paul