On Tuesday, August 5, 2003, 1:34:06 PM, William wrote:
>> One good reason for class level, though, is that the usage
>> information will then come out in ri/rj.
> I'm only passingly familiar with ri. Couldn't/shouldn't it
> also produce documentation for files? So that someone
> reading code and seeing "require 'tld/yama'" could say "ri
> tld/yama" to find out what this file provides?
You should familiarise yourself with it; it's an excellent
command-line tool.
It doesn't concern itself with filenames, though; all its data is
Marshalled objects that can be easily displayed in whatever output
format (99.9% of the time plain text) the user chooses.
ri and RDoc will One Day (TM) be unified by their common author Dave
Thomas, but it's a very difficult and/or time consuming task.
ri, at the moment, does not document the standard library. I have
created a modified codebase called "rj" which does document some of
it. This is thanks to James Britt's RImport, which converts RDoc XML
output into ri "input". The difference between ri and rj is the
ability to see multiple sets of data in different directories, and
treat them together or separately, depending on context. It is a
manual process to generate the data files, possibly excluding some
that are not suitable for rj (e.g. ExceptionForMatrix). The idea is
then to distribute the whole lot.
All that matters is that 'ri Net::FTP' doesn't work and 'rj Net::FTP'
does. And, thanks to you, all the other Net:: classes will soon be in
there. And then all the other stdlib stuff. And then REXML, etc., in
a "standard distribution", as opposed to "standard library", section.
That's looking pretty far into the future, and that doesn't include
treating 'ri net/ftp' differently than 'ri Net::FTP'. Having spelt
all that out, I submit this as a case for describing classes in class
comments instead of file comments. If there are several classes per
file, they can all have a verbose description if appropriate.
>> FYI, William, shortly before you joined the list we were working on
>> "rj" ("ri".succ), which is a modified ri to support the standard
>> library (you do know ri, right? :) I submitted some code, James
>> submitted a bug report, then I got busy with life, work, and
>> http://vim-ruby.rubyforge.net.
> I'm a vim user, so I appreciate your work on this very much.
> BTW, I notice on http://vim-ruby.rubyforge.org/ that the
> link to rubygarden doesn't work (missing http:// at the
> start, so is taken as relative).
Ah, thanks for that. There's a new release coming soon... (even
sooner if you use anonymous CVS ;)
Gavin
|
