ri Feature proposal

[Brian Schröder]

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

 

[gabriele renzi]

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]

Brian Schröder ha scritto:



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

 

[gabriele renzi]

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]

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]

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]

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