From: Ed Sinjiashvili <edsin@...>
Date: 2001-08-24T18:39:02+09:00
Subject: [ruby-talk:20264] Re: DocStrings

matz@ruby-lang.org (Yukihiro Matsumoto) writes:

> Hi,
> 
> In message "[ruby-talk:20261] DocStrings"
>     on 01/08/24, Ed Sinjiashvili <edsin@swes.saren.ru> writes:
> 
> |I was wondering why Ruby methods and classes lack documentation
> |strings. It seems to me that self-documented methods and classes are
> |very handy. We could use existing docstyle inside these strings and
> |generate docs from them. 
> 
> I think it's the responsibility of tools like IDE or ri.  Have you
> ever use ri by Dave Thomas?
No, I haven't, but as I got from your and other posts it's some kind
of man system. I was thinking about asking objects and methods about
their documentation at run-time. One example of this is elisp
documentation function: (documentation 'print). Another example of
docstrings usage is SPARK parser generator. It doesn't use them for
their initial purpose - it uses them for grammars. Here's example (in
Python):
class AutoExprParser(GenericASTBuilder):
    def p_expr(self, args):
        '''
            expr ::= expr + term
            expr ::= term
            term ::= term * factor
            term ::= factor
            factor ::= number
            factor ::= float
        '''
I might agree that such usage of docstrings is arguable but I
nevertheless think that self-documenting objects are very useful in OO
environment.


--
Regards, Ed