On Wed, Feb 11, 2009 at 1:59 PM, Paul Brannan <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 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 docstrings too. I first recall encountering them not in Python but in
GNU Emacs -- where you can (now) add them to variables, symbols, and
constants.

One thing funky in Python function docstrings is the that the indentation
after newlines is embedded 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 there's a
function to strip this out, but it still strikes me as an oddity. Not being
a Pythonista, I can can't say with confidence that this is/was the right way
to handle this, or that I even know what the best way to do so is.


>
> 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
>
>
>