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

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.

T.