Ruby Standard Library Doc. Status Report

Introduction

The following is a status report on nearly all of the important files in the Ruby standard library. Some are missing and will be added in time.

The priority indicates how important it is to properly document the given file. The status shows whether it has been attempted or not. The score is a mark out of 10 on how complete the documentation is.

If you'd like to help, pick a high-priority open file whose usage you are familiar with and start documenting! Grab the latest version from CVS, add some RDoc comments to it, and submit it to Gavin Sinclair. Several files already have comprehensive RD comments, so the conversion to RDoc is not difficult, just time-consuming. These are the ideal files for a first-timer.

The Report

 
lib/English.rb Pri: medium Stat: open Score: -
This is not a class or module, but a bunch of global variable aliases. It would probably be nice to document them anyway.
 
 
lib/base64.rb Pri: medium Stat: open Score: -
Easy pickings.
 
 
lib/benchmark.rb Pri: high Stat: done Score: 9.5
Benchmark.benchmark is a bit unclear.
 
 
lib/cgi.rb Pri: high Stat: done Score: 9
Not fully reviewed.
 
 
lib/cgi/session.rb Pri: high Stat: done Score: 9
Not fully reviewed.
 
 
lib/cgi/session/pstore.rb Pri: high Stat: done Score: 9
Not fully reviewed.
 
 
lib/complex.rb Pri: high Stat: done Score: 9
 
 
lib/csv.rb Pri: high Stat: done Score: 7
Looks pretty complete, but poorly formatted.
 
 
lib/date.rb Pri: high Stat: done Score: 7
Awaiting RDoc :def: feature to document dynamic methods.
 
 
lib/date/format.rb Pri: high Stat: open Score: -
I'm not sure what it does, but it's probably pretty important.
 
 
lib/delegate.rb Pri: high Stat: open Score: 3
Tricky one, but some good general documentation, instead of method by method, will help users to make use of this.
 
 
lib/drb/drb.rb Pri: high Stat: done Score: 10
 
 
lib/drb/eq.rb Pri: medium Stat: open Score: -
 
 
lib/drb/extserv.rb Pri: medium Stat: open Score: -
 
 
lib/drb/extservm.rb Pri: medium Stat: open Score: -
 
 
lib/drb/gw.rb Pri: medium Stat: open Score: -
 
 
lib/drb/invokemethod.rb Pri: medium Stat: open Score: -
 
 
lib/drb/observer.rb Pri: medium Stat: open Score: -
 
 
lib/drb/timeridconv.rb Pri: medium Stat: open Score: -
 
 
lib/e2mmap.rb Pri: low Stat: open Score: 3
Most of the documentation is there, but it's a weird library, probably only used by other libraries, and therefore a low priority. Not in good RDoc format.
 
 
lib/erb.rb Pri: low Stat: open Score: -
Low priority. People need to know how to use erb, not how it's implemented. A file-level comment could address this.
 
 
lib/eregex.rb Pri: low Stat: open Score: -
Not a serious file.
 
 
lib/fileutils.rb Pri: high Stat: done Score: 9
Some RDoc formatting errors. See EOF.
 
 
lib/finalize.rb Pri: medium Stat: open Score: 3
Skimpy RDoc comments exist. Need examples, etc.
 
 
lib/find.rb Pri: high Stat: done Score: 10
 
 
lib/forwardable.rb Pri: high Stat: open Score: 3
Some top-level comments. Better examples required. No method comments yet.
 
 
lib/ftools.rb Pri: high Stat: open Score: -
 
 
lib/getoptlong.rb Pri: high Stat: open Score: 3
Skimpy RDoc comments exist. Need examples, etc. Also explain that despite the wide use of getoptlong, optparse is more advanced.
 
 
lib/gserver.rb Pri: medium Stat: open Score: -
I've never heard of this, but it looks interesting.
 
 
lib/importenv.rb Pri: low Stat: open Score: -
It's a Perlish hack of a library, but a file-level comment would help.
 
 
lib/ipaddr.rb Pri: medium Stat: done Score: 7
Formatting needs work.
 
 
lib/jcode.rb Pri: medium Stat: open Score: -
File-level comment explaining what it is and does would be nice.
 
 
lib/logger.rb Pri: high Stat: done Score: 7
Formatting needs work.
 
 
lib/mailread.rb Pri: low Stat: open Score: -
Never heard of it. Looks good for its task, though (reading a whole mbox file is my guess).
 
 
lib/mathn.rb Pri: medium Stat: open Score: -
Not a commonly used/mentioned library, but looks OK. It loads 'complex', 'rational', and 'matrix', and defines some methods for inter-operation.
 
 
lib/matrix.rb Pri: high Stat: done Score: 9
A couple of todos at EOF.
 
 
lib/mkmf.rb Pri: high Stat: open Score: -
Not much of a library, but some usage notes at the file level would be good.
 
 
lib/monitor.rb Pri: medium Stat: done Score: 4
Serious issues remain. Is it superseded by something? (Wishful thinking.)
 
 
lib/mutex_m.rb Pri: medium Stat: open Score: 1
Some file-level documentation exists.
 
 
lib/net/ftp.rb Pri: high Stat: done Score: 9.5
A few things to tidy up.
 
 
lib/net/http.rb Pri: high Stat: done Score: 9
Not fully reviewed.
 
 
lib/net/imap.rb Pri: high Stat: done Score: 9
Not fully reviewed.
 
 
lib/net/pop.rb Pri: high Stat: done Score: 9
Not fully reviewed.
 
 
lib/net/smtp.rb Pri: high Stat: done Score: 9
Not fully reviewed.
 
 
lib/net/telnet.rb Pri: high Stat: done Score: 9
Not fully reviewed.
 
 
lib/observer.rb Pri: high Stat: done Score: 9
Put examples etc. at class level, not file level.
 
 
lib/open-uri.rb Pri: high Stat: open Score: 2
Some documentation exists, but it's a big file so a fair bit of work to do.
 
 
lib/open3.rb Pri: high Stat: open Score: -
Not much work to do here.
 
 
lib/optparse.rb Pri: high Stat: open Score: -
Thoroughly commented in RD.
 
 
lib/optparse/date.rb Pri: medium Stat: open Score: -
Small and weird, but usage description would help.
 
 
lib/optparse/shellwords.rb Pri: medium Stat: open Score: -
Small and weird, but usage description would help.
 
 
lib/optparse/time.rb Pri: medium Stat: open Score: -
Small and weird, but usage description would help.
 
 
lib/optparse/uri.rb Pri: medium Stat: open Score: -
Small and weird, but usage description would help.
 
 
lib/optparse/version.rb Pri: low Stat: open Score: -
It's an internal utility, accoring to the source code.
 
 
lib/ostruct.rb Pri: high Stat: open Score: -
Easy.
 
 
lib/parsedate.rb Pri: high Stat: open Score: -
Easy.
 
 
lib/pathname.rb Pri: medium Stat: open Score: -
Some effort involved here.
 
 
lib/ping.rb Pri: medium Stat: open Score: 9
Just some rearranging here and you're done.
 
 
lib/pp.rb Pri: medium Stat: open Score: -
Thoroughly commented in RD.
 
 
lib/prettyprint.rb Pri: low Stat: open Score: -
I doubt it's of use to many users; it's used by 'pp'.
 
 
lib/pstore.rb Pri: high Stat: open Score: -
 
 
lib/racc/parser.rb Pri: low Stat: open Score: -
I don't really know what this is, and it looks tough.
 
 
lib/rational.rb Pri: high Stat: open Score: -
 
 
lib/readbytes.rb Pri: low Stat: open Score: -
Easy.
 
 
lib/resolv-replace.rb Pri: medium Stat: open Score: -
Easy.
 
 
lib/resolv.rb Pri: high Stat: open Score: -
Difficult, though RDed already.
 
 
lib/scanf.rb Pri: high Stat: open Score: -
Thoroughly RDed.
 
 
lib/set.rb Pri: high Stat: done Score: 10
 
 
lib/shell.rb Pri: low Stat: open Score: -
 
 
lib/shellwords.rb Pri: low Stat: done Score: 9
 
 
lib/singleton.rb Pri: high Stat: open Score: 7
Pretty easy.
 
 
lib/sync.rb Pri: medium Stat: open Score: -
Looks difficult.
 
 
lib/tempfile.rb Pri: high Stat: open Score: 7
Some improvements to be made.
 
 
lib/thread.rb Pri: high Stat: done Score: 7
First pass; issues remain.
 
 
lib/thwait.rb Pri: medium Stat: done Score: 9
Need to ensure correctness.
 
 
lib/time.rb Pri: high Stat: done Score: 10
 
 
lib/timeout.rb Pri: high Stat: open Score: -
Easy.
 
 
lib/tmpdir.rb Pri: medium Stat: open Score: -
Pretty easy.
 
 
lib/tracer.rb Pri: low Stat: open Score: -
 
 
lib/tsort.rb Pri: medium Stat: done Score: 8
Lyle did a good job; just need to check consistency.
 
 
lib/un.rb Pri: medium Stat: open Score: -
Pretty easy.
 
 
lib/uri.rb Pri: high Stat: open Score: -
Only top-level documentation required. Give a good overview of the whole URI suite, and the files in the uri/ directory will not need as much effort.
 
 
lib/uri/common.rb Pri: medium Stat: open Score: -
 
 
lib/uri/ftp.rb Pri: medium Stat: open Score: -
 
 
lib/uri/generic.rb Pri: medium Stat: open Score: -
 
 
lib/uri/http.rb Pri: medium Stat: open Score: -
 
 
lib/uri/https.rb Pri: medium Stat: open Score: -
 
 
lib/uri/ldap.rb Pri: medium Stat: open Score: -
 
 
lib/uri/mailto.rb Pri: medium Stat: open Score: -
 
 
lib/weakref.rb Pri: high Stat: open Score: -
Usage example is there.