[ruby-talk:14730] Re: Rubydoc?

Holden Glova <[e-mail]> writes:

> > Is there an existing implementation of Javadoc like comments for
> 
> I'm working on it. I have done a basic proof of concept for myself 
> last week and it seemed to work pretty good for making a basic terse 
> look without any tagging yet. I have thought it would be better to use

Oops - I've got one too - it uses the irb parser to extract all the
class, module, and method features, and supports a kind of Wiki-like
markup in the comments. It seems pretty unobtrusive, which I like.

I'm stalled in two directions. First, I'm looking for a more complete
Ruby parser, because I want to do a better job of extracting parameter
definitions. Second, I'm still working out how I want the document
storage to work. My current thinking is that there'd be one or more
document databases on a system, and when you extract documentation it
would be put in to one of these. They would all support hyperlinking,
so if you had a comment that said

   # Works like Array#insert, but uses regular expressions

The system would be clever enough to recognize the pattern of an
instance method name, look it up in the various documentation
databases, and change it to a hyperlink.

I also need to work on backends. I'm making it 'ri' compatible, and
will have HTML generation, but I suspect there's the need for a lot
more.

Anyway, I'm still a long way off the final system, so I suspect it may
well give way to Holden's (as he seems further along). All I'd ask is
that we make the =begin stuff optional: the simpler the comments the
better. In fact, let me ask a simple question: why not take _any_
comment immediately preceding a class or method definition as the
documentation for that class or method? How often would than be a
problem? And it would be backwards compatible with stuff written
before this utility was even envisaged :)


Dave