Documenting DSLs

ruby-talk
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

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

···

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

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.

3

Thomas Sawyer 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

···

--
Posted via http://www.ruby-forum.com/\.

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:

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.

--
Florian Gilcher

smtp: flo@andersground.net
jabber: Skade@jabber.ccc.de
gpg: 533148E2

5

Florian Gilcher wrote:

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

I think you meant to say ERBook[1] (which generates beautiful user
manuals) rather than Inochi[2] (which is a framework for creating
gem-based libraries and command-line apps).

Cheers.

[1]: ERBook 9.2.1 — Write books, manuals, and documents in eRuby
[2]: inochi(1)

···

--
Posted via http://www.ruby-forum.com/\.