On Wed, Feb 11, 2009 at 1:59 PM, Paul Br= annan <pbrannan= @atdesk.com> wrote:

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 documentati= on for
variables -- only modules, classes, and methods. We're using epyd= oc,
and it has a special syntax for elements of the program that python
doesn't handle.

I like docstrings too. I first rec= all encountering them not in Python but in GNU Emacs -- where you can (now)= add them to variables, symbols, and constants.

One thing funky in P= ython function docstrings is the that the indentation after newlines is emb= edded into the string. For example in:

   def foo():
    '''This is a = multi-line
      string.'''

= The blanks before 'string' are there. In newer versions of Python t= here's a function to strip this out, but it still strikes me as an oddi= ty. Not being a Pythonista, I can can't say with confidence that this i= s/was the right way to handle this, or that I even know what the best way t= o do so is.

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

I don't like restructed text. The syntax and rules are complex, a= nd
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 u= p
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