From: Ryan Davis <ryand-ruby@...>
Date: 2005-05-28T18:06:04+09:00
Subject: Re: RI Conceptional Showstopper Bug.


On May 27, 2005, at 10:15 PM, Lothar Scholz wrote:

> Looked further into it and the situation is more worse then i
> expected. As RI does absolutely not handle the ruby key feature of
> open classes. If i write somewere a

Not true...

    --promiscuous, -p        When documenting a file that contains a  
module
                             or class also defined in other files, show
                             all stuff for that module/class in each  
files
                             page. By default, only show stuff  
defined in
                             that particular file.

---- cat blah.rb
class Blah
   ##
   # this is the main def method

   def in_main_def
   end
end
---- cat blah2.rb
class Blah

   ##
   # This is in the open class

   def in_open_class
   end
end
---- rdoc -p -o rdoc -f ri

                             blah.rb: c.
                            blah2.rb: c.
Generating RI...

Files:   2
Classes: 2
Modules: 0
Methods: 2
Elapsed: 0.240s
]---- find rdoc/rdoc -type f
rdoc/rdoc/Blah/cdesc-Blah.yaml
rdoc/rdoc/Blah/in_main_def-i.yaml
rdoc/rdoc/Blah/in_open_class-i.yaml

> class File
> def temp_dir; return "c:/myproject/temp"; end
> end
>
> The whole documentation for File is destroyed.

What do you mean by this? Are you just referring to the cdesc data as  
described below?

> Even if i generate the data in a different directory, the File class
> description is wrong as the "cdesc" files are not merged and we get 2
> different class descriptions instead of one and it is unclear which is
> selected (other then intuitive the pickup order is "system", "site",
> "user" and not the otherway round so overridding is not possible).

Are you intending for rdoc to be run against the core + user code? Or  
do you want rdoc to be run against user code that extends core  
functionality and somehow folds into core + user code? Would the user  
have their own copy of core? If not, how to deal with permission  
issues? And if not, how to deal with multiple users on the same  
system--surely userA would not want to see extensions to File made by  
userB that were not available to him.

As for "pickup order" as described above, that sounds like a bug, or  
at least a feature request. I don't know enough about it to be able  
to estimate how hard and/or how correct such a request is and will  
have to do more research into it. Please file a bug at http:// 
rubyforge.org/projects/rdoc/

> Thinks like this are going to make me tired.
> Easy of implementation seems to have always a higher priority then  
> correctness
> or fullfilling requirements. This is just one example, there are  
> hundert
> others out there in all the unfinished libraries and tools. This gives
> a bad reputation to the whole language and community.

I might say the same thing about your spelling. :P

As far as "correctness or fulfilling requirements" goes, I think that  
is a completely unnecessary (and rude) accusation. It was correct and  
fulfilling requirements as far as rdoc's original intent went. While  
rdoc tried to be for general use, ri did not. It was intended for  
system documentation and has not, to my understanding, ever tried to  
have a comparable feature-set to say, perldoc.

Lastly, I think it would be a much more constructive if you could  
objectively state your problem and simply ask for input. Editorials  
such as "Unforunately - but not suprising - i found an
important problems (sic)" and the whole paragraph quoted above do  
very little to support your cause.