Jeff Rose
4/27/2005 8:46:00 PM
Tilman Sauerbeck wrote:
> Jeff Rose <rosejn@gmail.com> [2005-04-26 17:18]:
>
>>Problem:
>> When I put this in the README file ":include:examples/sample.rb" it
>>does include the source, but it takes the # symbols off the comments in
>>the code, which makes it un-runnable if someone copy and pastes. (It
>>also looks lame...)
>>
>>Anyone know how to have it include the source but either turn off rdoc
>>completely or treat it as regular stuff rather than cutting out #'s?
>
>
> The attached patch should fix this, didn't try it though.
>
>
>
> ------------------------------------------------------------------------
>
> Only in ruby-1.8.2/lib/rdoc/markup/simple_markup: .preprocess.rb.swp
> diff -aur ruby-1.8.2.orig/lib/rdoc/markup/simple_markup/preprocess.rb ruby-1.8.2/lib/rdoc/markup/simple_markup/preprocess.rb
> --- ruby-1.8.2.orig/lib/rdoc/markup/simple_markup/preprocess.rb 2004-11-26 05:32:11.000000000 +0100
> +++ ruby-1.8.2/lib/rdoc/markup/simple_markup/preprocess.rb 2005-04-26 10:49:09.000000000 +0200
> @@ -43,7 +43,7 @@
> def include_file(name, indent)
> if (full_name = find_include_file(name))
> content = File.open(full_name) {|f| f.read}
> - res = content.gsub(/^#?/, indent)
> + res = content.gsub(/^\s*/, indent)
> else
> $stderr.puts "Couldn't find file to include: '#{name}'"
> ''
This patch is a little better, but still not quite there. It includes
the file and leaves the comments, but it indents weird and strips out
all of the blank lines. I tried playing with the regexp to fix this,
but I don't know what rdoc is trying to do with indenation etc. so it
wasn't working out. What is this :include: directive supposed to be
used for? Is this an incorrect usage?
On a different note, I was wondering if people had advice on documenting
dynamic code. My classes have a large number of generated methods
(similar to attr_accessor) which I'd like to document. Actually, I'd
really like to generate the documentation or something so that it can be
done intelligently to support continued changes etc. Is this something
people do? Until this point I hadn't thought about the added complexity
of documenting dynamic code, but it almost seems like examples are the
only way to go...
Thanks,
Jeff Rose