[ruby-talk:03684] Re: Ruby coding standard?

Hi,

Calvelo Daniel wrote:

> Mathieu Bouchard <[e-mail]> wrote:

...

> :> I have some Python, and would like to ask for one of its best features:
> :> docstrings.
> :> I don't know where the idea comes from; it is available in Matlab/Octave,
> :> in some flavours of lisp, and where else?
>
> : Well, I don't know what you are referring to. Is that comments that are
> : considered to be bound to a particular definition/declaration? if so,
> : SmallTalk has some of them, and Self has even more of them.
>
> In Python, a string placed right after a function or class declaration is
> put by the compiler into a variable called function.__doc__ ; it is
> afterwards available to the outside world.

...

> Sorry to introduce Python,

No need to be. We should take good ideas wherever we find them. I think it is
healthy for the Ruby World to have some awareness and discussion of various
ancestral, alternative, and/or competing languages.

> but I'm not yet comfortable enough with Ruby.
> You have this feature Python. If you declare in file aModule.py:
>
> # aModule.py
> def aFunc(anArg):
>   " A string right after the declaration. It is a 'docstring'."
>   print "hi"
>
> Then, in the interactive Python interpreter:
> >>> import aModule
> >>> print aModule.aFunc.__doc__
>  A string right after the declaration. It is a 'docstring'.
>
> Because I tend to test my programs with the interactive interpreter, I use
> this feature to look for usage messages, usage warnings and the like.
> Most of the standard libray has docstring documentation. The WHAT part
> I mentioned above is what may go into docstrings, along with some WHY.
>
> As for signatures, of course Ruby is not typed. But routines may require
> their arguments to respond to specific messages; it is IMHO useful to
> state some set of requirements on the arguments of a function. This is
> docstring-land.

I think this is a good idea. Although I tend to prefer frequent runs rather than
running interactively, I can see where this would be useful for others, plus I
think it could be very useful for future Ruby IDEs (integrated development
environments) and so on.

However I am not yet familiar with other Ruby documentation conventions/tools.
My main concern is that these sorts of things be complimentary and work well
together as a single integrated system, so that brief information that is useful
interactively doesn't have to be replicated if it is also useful for other
documentation. Does anyone else know if there is some reasonable way of doing
this?

--
Conrad Schneiker
(This note is unofficial and subject to improvement without notice.)