From: Trans <transfire@...>
Date: 2008-08-14T19:11:20+09:00
Subject: Re: Documenting DSLs



On Aug 11, 10:20 am, Trans <transf...@gmail.com> wrote:
> Hey, has anyone thought about or worked on a "next gen" documentation
> system for handling Ruby DSLs?
>
> I have some code that I'd really like to DSLify, but I don't want to
> loose the RDocs. Let me give a simple example.
>
>   # What mysev does.
>   class MyService < Service
>
>     register :myserv
>
>     action :foo
>
>     # What foo does.
>     def foo
>       ...
>     end
>
>   end
>
> This is a (simplified but) common pattern is some of my work. I'd love
> to write this as a DSL:
>
>   # What mysev does.
>   service :myserve do
>
>     # What foo does.
>     action :foo do
>       ...
>     end
>
>   end
>
> Ideally, I suppose the doc tool could be taught that #service
> translates into a subclass of Service, and #action translates into a
> method. (Not sure how feasible that is though.)
>
> No doubt I could roll my own special documentation tool for my
> personal needs, but I already have too much to do. I'd much prefer a
> general solution.

Well, since no one responded here I can only assume there are no
solutions out there. So I was thinking how I might go about addressing
the issue.

It occurs to me that probably the easiest and potentially most
powerful means of documenting ruby methods and classes/modules is to
do it in Ruby itself.

  doc 'What mysev does.'

  service :myserve do

    doc 'What foo does.'

    action :foo do
      ...
    end

  end

Associating the docs to their corresponding code could be implemented
in general via Object#method_added and inherited(?). One could also
add their own #capture_docs call in places of special importance.
Under normal operation of course #doc is just and noop.

This seems like such an interesting and potentially powerful way of
going about things, I'm thinking of creating an implementation.

Then it occurs to me, assuming of course there's is no terrible flaw
in this idea that I've overlooked, wouldn't it be crazy cool if in
Ruby '#' was a special method call? These aren't your father's
comments! Oh no. They a living, breathing comments ;)

Thoughts?
T.