# Documenting DSLs

**URL:** <https://www.ruby-forum.com/t/documenting-dsls/176945>\
**Category:** Ruby\
**Created:** [October 8, 2009, 6:08pm UTC](https://www.ruby-forum.com/t/documenting-dsls/176945 "2009-10-08T18:08:57Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![tcsnide](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/eb8c5e/32.png) [@tcsnide](https://www.ruby-forum.com/u/tcsnide)\
**Post date:** [October 8, 2009, 6:08pm UTC](https://www.ruby-forum.com/t/documenting-dsls/176945/1 "2009-10-08T18:08:57Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![tcsnide](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/eb8c5e/32.png) [@tcsnide](https://www.ruby-forum.com/u/tcsnide)\
**Post date:** [October 8, 2009, 8:21pm UTC](https://www.ruby-forum.com/t/documenting-dsls/176945/2 "2009-10-08T20:21:16Z")

</div>

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](http://rdoc.rubyforge.org/RDoc/Parser/Ruby.html)

---

<div class="post-metadata">

**Author:** ![tcsnide](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/eb8c5e/32.png) [@tcsnide](https://www.ruby-forum.com/u/tcsnide)\
**Post date:** [October 9, 2009, 1:29pm UTC](https://www.ruby-forum.com/t/documenting-dsls/176945/3 "2009-10-09T13:29:47Z")

</div>

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](http://article.gmane.org/gmane.comp.lang.ruby.documentation/1102)

-r

---

<div class="post-metadata">

**Author:** ![tcsnide](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/eb8c5e/32.png) [@tcsnide](https://www.ruby-forum.com/u/tcsnide)\
**Post date:** [October 9, 2009, 6:16pm UTC](https://www.ruby-forum.com/t/documenting-dsls/176945/4 "2009-10-09T18:16:40Z")

</div>

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: removed\_email\_address@domain.invalid  
jabber: removed\_email\_address@domain.invalid  
gpg: 533148E2

---

<div class="post-metadata">

**Author:** ![tcsnide](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/eb8c5e/32.png) [@tcsnide](https://www.ruby-forum.com/u/tcsnide)\
**Post date:** [October 10, 2009, 9:43am UTC](https://www.ruby-forum.com/t/documenting-dsls/176945/5 "2009-10-10T09:43:40Z")

</div>

Florian G. wrote:

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

I think you meant to say ERBook[1](http://snk.tuxfamily.org/lib/erbook/) (which generates beautiful user  
manuals) rather than Inochi[2](http://snk.tuxfamily.org/lib/inochi/) (which is a framework for creating  
gem-based libraries and command-line apps).

Cheers.