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-schroeder.de/
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?
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)
···
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.
------------------------------------------------------------------------
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
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-schroeder.de/
Dave Thomas 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
···
On Sep 28, 2004, at 16:31, Brian Schröder wrote:
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 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
···
On Sep 29, 2004, at 6:04 AM, Brian Schröder wrote:
On Sep 28, 2004, at 16:31, Brian Schröder wrote:
Regards,
Brian