[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

ri Feature proposal

Brian Schröder

9/28/2004 9:32:00 PM

Hello Group,

what do you think? I think it would make sense to include the file in
which a function is defined into the ri output. On my debian system with
a mostly plain vanilla ruby installation ri yields for example:

$ ri Array#abbrev
----------------------------------------------------------- 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.

%w{ car cone }.abbrev #=> { "ca" => "car", "car" => "car",
"co" => "cone", "con" => cone",
"cone" => "cone" }

$ irb
irb(main):001:0> %w{car cone}.abbrev
NoMethodError: undefined method `abbrev' for ["car", "cone"]:Array
from (irb):1

So I deduce that abbrev is declared in some library. But where it is can
only be found by using grep in the library directory. It would be nice
to have something like:

defined in: namespace/xyz.rb

included in the ri output.

Regards,

Brian Schröder
--
Brian Schröder
http://ruby.brian-sch...
6 Answers

gabriele renzi

9/28/2004 9:55:00 PM

0

Brian Schröder ha scritto:


> So I deduce that abbrev is declared in some library. But where it is can
> only be found by using grep in the library directory. It would be nice
> to have something like:
>
> defined in: namespace/xyz.rb
>
> included in the ri output.
>

agreed, but what about stuff defined in multiple files?

Brian Schröder

9/29/2004 12:04:00 AM

0

gabriele renzi wrote:
> Brian Schröder ha scritto:
>
>
>> So I deduce that abbrev is declared in some library. But where it is
>> can only be found by using grep in the library directory. It would be
>> nice to have something like:
>>
>> defined in: namespace/xyz.rb
>>
>> included in the ri output.
>>
>
> agreed, but what about stuff defined in multiple files?
>

That is the one problem. What can be declared in multiple files?
I see:
- Classes
- Modules

Functions are always in one class. The best solution would be to list
all the files where the class is declared.

regards,

Brian
--
Brian Schröder
http://ruby.brian-sch...

gabriele renzi

9/29/2004 8:33:00 AM

0

Brian Schröder ha scritto:


> Functions are always in one class. The best solution would be to list
> all the files where the class is declared.
>

I think that there should be someway to tel RDoc that some stuff is just
an expansion to an existing class, so that it could show both the 'main'
file and the 'extension' one. but this would probably be too much of an
hassle for devs. So I add a +1 for your idea :)

Dave Thomas

9/29/2004 11:41:00 AM

0


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

Brian Schröder

9/29/2004 1:04:00 PM

0

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?

Regards,

Brian

Mark Hubbart

9/29/2004 5:40:00 PM

0


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
>