ri needs to tell me what to require

[Ben Giddings]

% ri File.copy

------------------------------------------------------------- File::copy
File::copy(from, to, verbose = false)
------------------------------------------------------------------------
Copies a file +from+ to +to+ using #syscopy. If +to+ is a
directory, copies +from+ to +to/from+. If +verbose+ is true, +from
-> to+ is printed.

Yay! That's what I want!

irb(main):001:0> File.copy("foo", "bar")
NoMethodError: undefined method `copy' for File:Class
from (irb):1

*cry*

It turns out that File.copy is defined in 'ftools', but I have no idea
how I'm supposed to know that.

Ben

 

[Brian Schröder]

% ri File.copy

------------------------------------------------------------- File::copy
File::copy(from, to, verbose = false)
------------------------------------------------------------------------
Copies a file +from+ to +to+ using #syscopy. If +to+ is a
directory, copies +from+ to +to/from+. If +verbose+ is true, +from
-> to+ is printed.

Yay! That's what I want!

irb(main):001:0> File.copy("foo", "bar")
NoMethodError: undefined method `copy' for File:Class
from (irb):1

*cry*

It turns out that File.copy is defined in 'ftools', but I have no idea
how I'm supposed to know that.

Ben

In principle a +1 from me, but check also:

http://groups.google.de/[email protected]

regards,

Brian

 

[Ben Giddings]

In principle a +1 from me, but check also:

http://groups.google.de/groups?threadm=6D24974B-123E-11D9-8C3F
-000A95D2DFAE%40mac.com

Which says:

In principle then, the file 'yaml/foo.rb' should contain some kind of
comment saying "hey, if you want the functionality that this file
provides, require 'yaml' not this file". That way people who are
looking at that file in their favourite editor can know how to get
access to those functions. It should be possible to do that in a way
that rdoc can pick up on it, right?

Ben

 

[Brian Schröder]

Which says:


In principle then, the file 'yaml/foo.rb' should contain some kind of
comment saying "hey, if you want the functionality that this file
provides, require 'yaml' not this file". That way people who are
looking at that file in their favourite editor can know how to get
access to those functions. It should be possible to do that in a way
that rdoc can pick up on it, right?

Yes, you could put this comment at the end of the description of each function. But this is a lot of "repeat yourself", and who wants that?

So it seems someone has to think about extending rdoc with some new meta commands, create a patch, discuss and standardize it and get it included. Sadly thats more work than I have time, so I just hope that someone else will do this. Not the nice way, but I don't see another possibility.

Regards,

Brian

 

[Ben Giddings]

Yes, you could put this comment at the end of the description of each
function. But this is a lot of "repeat yourself", and who wants that?

Would it really need to be at the beginning of each function, or could
one command at the top of the file do it?

I don't know how the internals of rdoc work at all, but it seems that
that should be possible, just some little comment at the top saying:

# To use any of the functions from this file
# require 'yaml'

So it seems someone has to think about extending rdoc with some new
meta commands, create a patch, discuss and standardize it and get it
included. Sadly thats more work than I have time, so I just hope that
someone else will do this. Not the nice way, but I don't see another
possibility.

I don't know how rdoc works, so that might be necessary. I was looking
into customizing some rdoc output the other day, and it seemed like
there was a lot going on in there that I didn't understand.

Maybe it's time for the next big leap in rdoc functionality.

Ben