From: Florian Gross <flgr@...>
Date: 2004-10-20T19:59:18+09:00
Subject: Re: documentation as source

Pe�a, Botp wrote:

>>    #   # This creates a Regexp which will match 3 "foo"s.
>>    #   re = Regexp::English.literal("foo" * 3)
>>    #   re.match("foofoofoo")[0] # => "foofoofoo"
>>
> many times, I have multi-# on a line on my code. Blame me lazy and my editor
> :-)

Which is not explicitly bad. But do you also have indented text in your 
RDoc documentation? test-extract only looks for sample code in RDoc 
documentation which is comments that are directly before a method or 
class definition like this:

# Here goes the documentation.
#   Here goes the sample code.
def foo; end

But not like this:

def foo
   # Just a random comment.
   #   With something random that is indented.
end

> is it possible to put (Example) tags? =)
> 
>      #   #Example: This creates a Regexp which will match 3 "foo"s.
>      #   re = Regexp::English.literal("foo" * 3)
>      #   re.match("foofoofoo")[0] # => "foofoofoo"
>      #   #EndExample <-- this would be optional if it hits another #Example

See above. Is this really necessary? If I add support for this then I 
will need to remove the current rule which is less restrictive.

If we really need such a rule I think I would change it so that it would 
match anything that is indented and preceded by optional empty lines and 
  one of the words "example", "sample", "code".

That would still allow you to write:

# This method doubles an object. The object has to respond to +*+.
# It is used like in this example:
#
#   double(10)       # => 20
#   double("hello")  # => "hellohello"
#   double("")       # => ""
#   double([1, 2])   # => [1, 2, 1, 2]
#   double(:foo)     # raises NoMethodError
def double(obj)
   obj * 2
end

> kind regards -botp

More regards,
Florian Gross