From: Florian Gross <flgr@...>
Date: 2004-11-27T00:42:56+09:00
Subject: Re: [RDOC] Using unit-tests as examples for a documentation

Dave Thomas wrote:

> I'm not sure what you're asking for here--could you explain at bit more? 
> (RDoc will already set this indented code as code, won't it?)

I'm thinking along the lines of a "sample code" icon or something 
similar that can be clicked to display or hide the embedded sample code 
and possibly also setup code that needs to be run for actually making 
the sample code work for the HTML output.

Maybe something like in this simplified example:

class KeyedList
   ...

   # Removes all items from a keyed list.
   #
   # % aList = KeyedList["foo", "bar", "qux"]
   # | aList.clear
   # | aList.size # => 0
   def clear
     size.times { pop }
   end
end

Where "%" would by default be hidden and could be uncovered by clicking 
the icon. I'm not sure about the symbols so feel free to change them to 
something that makes more sense for you.

I think the biggest point would however be formatting samples 
consistently so that they can be distinguished easily from other things 
that make sense in a whitespace preserved area.