Documenting DSLs

Ruby
1

Has anyone done any work on documenting Ruby DSLs? Eg. RDoc can
document this:

This plugin …

class MyThing < Plugin
# This does …
def some
…
end
end

But if one were to make a DSL out of it, say:

This plugin …

plugin ‘MyThing’ do
# This does …
define ‘some’ do
…
end
end

Then no RDocy.

2

On Oct 8, 2009, at 09:08 , Intransition wrote:

Then no RDocy.
Seems you’re not in “transition” anymore.

2.1.0 / 2008-07-20
• 3 Major Enhancements:
• RDoc now knows about meta-programmed methods,
seeRDoc::Parser::Ruby

http://rdoc.rubyforge.org/RDoc/Parser/Ruby.html

3

Thomas S. wrote:

Has anyone done any work on documenting Ruby DSLs? Eg. RDoc can
document this:
# This does …
define ‘some’ do
…
end
end

Then no RDocy.

I had to ask the same question recently.

http://article.gmane.org/gmane.comp.lang.ruby.documentation/1102

-r

4

YARD can be pretty easily made to parse such stuff.

But extending the generated HTML is kind of unintuitive, IMHO.

If you want narrative documentation, Inochi is a gem that tries
to fix this problem.

Regards,
Florian

On Oct 8, 2009, at 1:38 PM, Intransition wrote:

Then no RDocy.

–
Florian G.

smtp: [email protected]
jabber: [email protected]
gpg: 533148E2

5

Florian G. wrote:

If you want narrative documentation, Inochi
is a gem that tries to fix this problem.

I think you meant to say ERBook1 (which generates beautiful user
manuals) rather than Inochi2 (which is a framework for creating
gem-based libraries and command-line apps).

Cheers.