ri Feature proposal

Discussion in 'Ruby' started by Brian Schröder, Sep 28, 2004.

  1. 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, Sep 28, 2004
    #1
    1. Advertising

  2. 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?
     
    gabriele renzi, Sep 28, 2004
    #2
    1. Advertising

  3. 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/
     
    Brian Schröder, Sep 29, 2004
    #3
  4. 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 :)
     
    gabriele renzi, Sep 29, 2004
    #4
  5. Brian Schröder

    Dave Thomas Guest

    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
     
    Dave Thomas, Sep 29, 2004
    #5
  6. 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
     
    Brian Schröder, Sep 29, 2004
    #6
  7. Brian Schröder

    Mark Hubbart Guest

    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
    >
     
    Mark Hubbart, Sep 29, 2004
    #7
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. christopher diggins

    Java Feature Proposal

    christopher diggins, Feb 4, 2004, in forum: Java
    Replies:
    18
    Views:
    583
    Adam Jenkins
    Feb 10, 2004
  2. David Murmann

    Feature Proposal: Sequence .join method

    David Murmann, Sep 30, 2005, in forum: Python
    Replies:
    10
    Views:
    463
    David Murmann
    Oct 1, 2005
  3. Jp Calderone
    Replies:
    2
    Views:
    267
    Alex Martelli
    Oct 8, 2005
  4. coldpizza
    Replies:
    45
    Views:
    950
    coldpizza
    Jan 29, 2008
  5. Paul Rubin

    feature proposal, debug on exception

    Paul Rubin, May 21, 2008, in forum: Python
    Replies:
    3
    Views:
    235
    Ville M. Vainio
    May 21, 2008
Loading...

Share This Page