From: Tom Cloyd <tomcloyd@...>
Date: 2009-07-16T00:52:00+09:00
Subject: Re: rdoc run-time length question

Justin Collins wrote:
> 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
>
>
Justin,

Thanks very much for the help.

* Yes, the -x /doc parameter solves the run-time doubling problem. 
Thanks. I didn't see that solution because I didn't see what the problem 
really was, and your explanation of it was enlightening. However, the 
file copy does NOT go into /doc/files. Rdoc simply copies everything, 
including the current /doc dir into a NEW /doc dir, we that we get, over 
time /doc/doc/doc/doc/doc/doc/doc..... And this is good for what?

Why in blazes would rdoc do this dumb thing - copying itself over and 
over with each run? If there's some purpose to it, why is it not documented?

* Also - the "-d" is worthless. Diagram generation via graphviz's dot 
just isn't available. I have graphviz installed (I'm running Kubuntu 
Linux 9.04) and have been using it for multiple projects. I've been all 
over the graphviz.org website, and there is NO separate "dot" download, 
as referred to in this section of the output from "rdoc -h":

-d, --diagram Generate diagrams showing modules and classes. You need 
dot V1.8.6 or later to
use the --diagram option correctly. Dot is available from 
http://graphviz.org

One can only install the "graphviz" package, which I know includes 
"dot", 'cause I call it all the time. However, I can discover NO way to 
make rdoc generate those diagrams referred to.  Am I missing something?

t.

-- 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website) 
<< sleightmind.wordpress.com >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~