On Sep 29, 2004, at 6:04 AM, Brian Schr?der wrote:

> Dave Thomas wrote:
>
>>
>> On Sep 28, 2004, at 16:31, Brian Schr?der wrote:
>>
>>> It would be nice to have something like:
>>>
>>>   defined in: namespace/xyz.rb
>>>
>>> included in the ri output.
>>
>>
>> Excellent idea. The only problem is that, as things stand, this isn't  
>> easily knowable, as the file containing the method definition may not  
>> be the one that you end up requiring into your Ruby source. For  
>> example, the various YAML methods are defined in files in the yaml/  
>> directory, but you don't require these into your code. Instead you  
>> say
>>
>>   require "yaml"
>>
>> and it drags them in for you.
>>
>> Perhaps the solution might be to extend the code examples in the  
>> documentation to include any necessary 'require' statements, so your  
>> abbrev example would become:
>>
>> -----------------------------------------------------------  
>> Array#abbrev
>>      abbrev(pattern = nil)
>> ---------------------------------------------------------------------- 
>> --
>>      Calculates the set of unambiguous abbreviations for the strings  
>> in
>>      self. If passed a pattern or a string, only the strings matching
>>      the pattern or starting with the string are considered.
>>
>>        require 'abbrev'
>>        %w{ car cone }.abbrev   #=> { "ca" => "car", "car" => "car",
>>                                      "co" => "cone", "con" => cone",
>>                                      "cone" => "cone" }
>>
>>
>> Cheers
>>
>> Dave
>>
>>
> Hello Dave,
>
> that would certainly be a solution.
>
> As I like shoving work to the computer, I'd propose the following:
>
> If there is a tag
>
> # :require_as: yaml
>
> for the (file, module, class, function) output for everything that is  
> in the scope of the tag as
>
> defined in: filename
> require as: yaml
>
> otherwise output
>
> defined in: filename
> require as: filename
>
> what do you think?

those would be nice extensions to RDoc...

Here's another thought: would it be difficult to record the dependency  
trees?

For example, mathn.rb requires complex.rb. math-mode.rb requires  
mathn.rb. So, the documentation for Complex.new could include something  
like this:

Complex::new
- defined in: complex.rb
- required by: mathn.rb, math-mode.rb

As a side note, I can't seem to pull up file documentation via ri. Some  
libs have very useful documentation in the file-level docs; It would be  
nice to be able to pull them up. Combined with "defined in:" and  
"required by:" notes in the ri docs, It would make searching the  
documentation a bit easier - once you find the class/method you want to  
use, just check the file dependencies, ri them, and determine which lib  
file is most appropriate to include.

cheers,
Mark

>
> Regards,
>
> Brian
>