From: Justin Collins <justincollins@...>
Date: 2009-07-15T16:21:07+09:00
Subject: Re: rdoc run-time length question

Tom Cloyd wrote:
> Justin Collins wrote:
>> Tom Cloyd wrote:
>>> Tom Cloyd wrote:
>>>> I note that if I don't delete the relevant /docs dir, then each 
>>>> time I run rdoc on my ruby file it takes longer, and reports the 
>>>> involvement of ever more files. Can someone explain this behavior? 
>>>> It's dramatic how much better (quicker) it runs if I delete the doc 
>>>> dir every time.
>>>>
>>>> t.
>>>>
>>> A little documentation:
>>>
>>> tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$ ls
>>> SN.rb <= a single module, containing 6 classes
>>> tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$ rdoc -N -U
>>> Parsing sources with 2 thread(s)...
>>> 100% [ 1/ 1]  SN.rb
>>>
>>> Generating Darkfish...
>>>
>>> Files:   1
>>> Classes: 6
>>> Modules: 1
>>> Methods: 58
>>> Elapsed: 7.3s
>>>
>>> tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$ rdoc -N -U <= 
>>> immediate rerun, after trivial file change
>>> Parsing sources with 2 thread(s)...
>>> 100% [16/16]  doc/index.html
>>>
>>> Generating Darkfish...
>>>
>>> Files:   16
>>> Classes: 6
>>> Modules: 1
>>> Methods: 58
>>> Elapsed: 17.4s
>>> tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$
>>>
>>> As you can see, the file  count and elapsed time doubles.
>>>
>>> tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$ rdoc -N -U
>>> Parsing sources with 2 thread(s)...
>>> Unrecognized directive 'd' in doc/doc/SN/SetNet_html.html <=?????
>>> 100% [31/31]  doc/index.html
>>>
>>> Generating Darkfish...
>>>
>>> Files:   31
>>> Classes: 6
>>> Modules: 1
>>> Methods: 58
>>> Elapsed: 39.2s
>>> tomc@tomc-desktop:~/Ruby-work/setnet/lib/setnet$
>>>
>>> File count and elapsed time just keeps doubling.
>>>
>>> t.
>>>
>>
>>
>> It's processing the doc/ directory.
>>
>> -Justin
>>
>>
> I don't understand - processing involves doubling the time and files. 
> This quickly becomes a monster. Why? Am I running this thing wrong? I 
> don't see anything in the documentation about this (from "rdoc -h"). 
> I'm wondering what I don't know here.
>
> t.

I would not say  you are running it wrong (though I am far from an rdoc 
master). The default behavior when you run rdoc is for it to parse all 
files in the current directory and any subdirectories. Then it generates 
the documentation and puts it in the doc/ directory.

Okay.

But when it does that, it also puts a copy of -everything- it parsed 
into the doc/files/ directory.

Now you run rdoc again. This time, it parses and -copies- all the same 
files it did before, -plus- everything in the doc/ directory. That means 
all the documentation generated before gets copied and put into 
doc/files/. Including the old doc/files/

You can try using --exclude doc/ so that it does not parse the doc/ 
directory.

I am still not sure that is clear...but I hope it helps a little bit?

-Justin