Ri - what does it know?

(Mark Volkmann) #1

It's unclear to me what I can expect ri to know about. Does this
differ depending on whether I used the one-click installer or built
from source? Should ri know about every built-in class/module? Should
ri know about anything in the standard library? When I install
something new, do the installers typically add documentation that is
accessible to ri?

···

--
R. Mark Volkmann
Partner, Object Computing, Inc.

(Eric Hodel) #2

ri should know about just about everything in the core. It should know about all extensions mentioned in ext/.document, and all standard library classes/modules mentioned in lib/.document in the source.

Currently, rubygems does not generate ri information. It is commented out.

···

On 23 Aug 2005, at 13:24, Mark Volkmann wrote:

It's unclear to me what I can expect ri to know about. Does this
differ depending on whether I used the one-click installer or built
from source? Should ri know about every built-in class/module? Should
ri know about anything in the standard library? When I install
something new, do the installers typically add documentation that is
accessible to ri?

--
Eric Hodel - drbrain@segment7.net - http://segment7.net
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04

(Mark Volkmann) #3

> It's unclear to me what I can expect ri to know about. Does this
> differ depending on whether I used the one-click installer or built
> from source? Should ri know about every built-in class/module? Should
> ri know about anything in the standard library? When I install
> something new, do the installers typically add documentation that is
> accessible to ri?

ri should know about just about everything in the core. It should
know about all extensions mentioned in ext/.document, and all
standard library classes/modules mentioned in lib/.document in the
source.

It doesn't seem to know about everything in the standard library. For
example, all of the following result in "Nothing know about ...".

ri webrick
ri WEBrick
ri HTTPServlet

···

On 8/23/05, Eric Hodel <drbrain@segment7.net> wrote:

On 23 Aug 2005, at 13:24, Mark Volkmann wrote:

Currently, rubygems does not generate ri information. It is
commented out.

--
R. Mark Volkmann
Partner, Object Computing, Inc.

(Lothar Scholz) #4

Hello Eric,

It's unclear to me what I can expect ri to know about. Does this
differ depending on whether I used the one-click installer or built
from source? Should ri know about every built-in class/module? Should
ri know about anything in the standard library? When I install
something new, do the installers typically add documentation that is
accessible to ri?

ri should know about just about everything in the core. It should
know about all extensions mentioned in ext/.document, and all
standard library classes/modules mentioned in lib/.document in the
source.

No. At least not the ri database that comes with the one-click-installer.
It only nows everything (at least what is documented) inside ruby.exe

Currently, rubygems does not generate ri information. It is
commented out.

Which is good, because ri has a broken design that does not fullfill with
the purpose of a package manager. It would otherwise slowly fill your
system with garbage. I worked around that in ArachnoRuby, but it
should be fixed in "rdoc.rb".

···

On 23 Aug 2005, at 13:24, Mark Volkmann wrote:

--
Best regards, emailto: scholz at scriptolutions dot com
Lothar Scholz http://www.ruby-ide.com
CTO Scriptolutions Ruby, PHP, Python IDE 's

(Eric Hodel) #5

ri should know about just about everything in the core. It should
know about all extensions mentioned in ext/.document, and all
standard library classes/modules mentioned in lib/.document in the
source.

It doesn't seem to know about everything in the standard library.

That's because lib/.document and ext/.document mention only a handful of files.

For example, all of the following result in "Nothing know about ...".

ri webrick
ri WEBrick
ri HTTPServlet

Which is exactly as it should be, WEBrick is not mentioned in lib/.document:

$ grep -i webrick lib/.document
$

Somebody needs to make sure that they're OK to be RDoc'd and get them added to lib/.document.

···

On 23 Aug 2005, at 14:09, Mark Volkmann wrote:

--
Eric Hodel - drbrain@segment7.net - http://segment7.net
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04

(Eric Hodel) #6

I don't see any bugs matching that description in the rdoc bug or feature requests tracker.

http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
http://rubyforge.org/tracker/?atid=2475&group_id=627&func=browse

···

On 23 Aug 2005, at 15:27, Lothar Scholz wrote:

Hello Eric,

> Currently, rubygems does not generate ri information. It is
> commented out.

Which is good, because ri has a broken design that does not fullfill with
the purpose of a package manager. It would otherwise slowly fill your
system with garbage. I worked around that in ArachnoRuby, but it
should be fixed in "rdoc.rb".

--
Eric Hodel - drbrain@segment7.net - http://segment7.net
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04

(James Britt) #7

Eric Hodel wrote:

...

Which is exactly as it should be, WEBrick is not mentioned in lib/.document:

$ grep -i webrick lib/.document
$

Somebody needs to make sure that they're OK to be RDoc'd and get them added to lib/.document.

What's the criteria? I can think of two things offhand:

* The code does not redefine any other classes (as this tends to boink
the original ri files.) E.g., it is not adding or altering methods in,
say, Array or String. (Or, if it does redefine stuff, that part does not get ri'ed. I think nodoc can handle that.)

* The code has some useful docs.

Certainly it would be nice to get those doc'ed libs from the stdlib into
ri by default.

James

···

--

http://www.ruby-doc.org - The Ruby Documentation Site
http://www.rubyxml.com - News, Articles, and Listings for Ruby & XML
http://www.rubystuff.com - The Ruby Store for Ruby Stuff
http://www.jamesbritt.com - Playing with Better Toys

(Lothar Scholz) #8

Hello Eric,

···

On 23 Aug 2005, at 15:27, Lothar Scholz wrote:

Hello Eric,

> Currently, rubygems does not generate ri information. It is
> commented out.

Which is good, because ri has a broken design that does not
fullfill with
the purpose of a package manager. It would otherwise slowly fill your
system with garbage. I worked around that in ArachnoRuby, but it
should be fixed in "rdoc.rb".

I don't see any bugs matching that description in the rdoc bug or
feature requests tracker.

http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
http://rubyforge.org/tracker/?atid=2475&group_id=627&func=browse

Okay i added this, but what sense does it make as long as nobody is
maintaining "rdoc" ?

--
Best regards, emailto: scholz at scriptolutions dot com
Lothar Scholz http://www.ruby-ide.com
CTO Scriptolutions Ruby, PHP, Python IDE 's

(Eric Hodel) #9

Eric Hodel wrote:

Which is exactly as it should be, WEBrick is not mentioned in lib/.document:
$ grep -i webrick lib/.document
$
Somebody needs to make sure that they're OK to be RDoc'd and get them added to lib/.document.

What's the criteria? I can think of two things offhand:

* The code does not redefine any other classes (as this tends to boink
the original ri files.) E.g., it is not adding or altering methods in,
say, Array or String. (Or, if it does redefine stuff, that part does not get ri'ed. I think nodoc can handle that.)

I think if the documentation mentions where non-core methods come from that'd be enough. There are a few non-core methods listed in ri (Time#iso8601 comes from time.rb). Maybe just adding "require 'foo'" to the synopsis.

Personally, I'd rather see some documentation that confuses origin over no docs.

* The code has some useful docs.

Certainly it would be nice to get those doc'ed libs from the stdlib into
ri by default.

Most importantly, post patches to ruby-core. I RDoc'd resolv.rb a few months back.

···

On 23 Aug 2005, at 17:56, James Britt wrote:

--
Eric Hodel - drbrain@segment7.net - http://segment7.net
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04

(Eric Hodel) #10

Ryan Davis (and myself) have taken over maintainership.

···

On 24 Aug 2005, at 04:06, Lothar Scholz wrote:

Hello Eric,

> On 23 Aug 2005, at 15:27, Lothar Scholz wrote:

Hello Eric,

> Currently, rubygems does not generate ri information. It is
> commented out.

Which is good, because ri has a broken design that does not
fullfill with
the purpose of a package manager. It would otherwise slowly fill your
system with garbage. I worked around that in ArachnoRuby, but it
should be fixed in "rdoc.rb".

> I don't see any bugs matching that description in the rdoc bug or
> feature requests tracker.

> http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
> http://rubyforge.org/tracker/?atid=2475&group_id=627&func=browse

Okay i added this, but what sense does it make as long as nobody is
maintaining "rdoc" ?

--
Eric Hodel - drbrain@segment7.net - http://segment7.net
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04

(James Britt) #11

Eric Hodel wrote:

...

What's the criteria? I can think of two things offhand:

* The code does not redefine any other classes (as this tends to boink
the original ri files.) E.g., it is not adding or altering methods in,
say, Array or String. (Or, if it does redefine stuff, that part does not get ri'ed. I think nodoc can handle that.)

I think if the documentation mentions where non-core methods come from that'd be enough. There are a few non-core methods listed in ri (Time#iso8601 comes from time.rb). Maybe just adding "require 'foo'" to the synopsis.

Personally, I'd rather see some documentation that confuses origin over no docs.

The issue is not user confusion, but rdoc/ri obliterating the proper ri yml files with some new file generated when processing a library that just happens to include something like

class Array
   def foo
      # ...
   end
end

James

···

On 23 Aug 2005, at 17:56, James Britt wrote: