Status Report

## 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

ext/enumerator/enumerator.c | Pri: high | Stat: done | Score: 7
Some methods unclear. Overall example usage would be good.
ext/etc/etc.c | Pri: high | Stat: done | Score: 8
Add example usage to the module documentation and it's perfect.
ext/fcntl/fcntl.c | Pri: medium | Stat: done | Score: 10
ext/iconv/iconv.c | Pri: medium | Stat: done | Score: 7
Mostly done; one or two things to iron out.
ext/strscan/strscan.c | Pri: medium | Stat: done | Score: 9
One FIXME, and #initialize might be incorrectly documented.
ext/zlib/zlib.c | Pri: high | Stat: done | Score: 6
Just entered docs from author's RD documentation, improved English and formatting, and added class/module docs. Some undocumented methods and some unclear ones. More examples and general effort needed.
lib/English.rb | Pri: medium | Stat: done | Score: 10
lib/abbrev.rb | Pri: medium | Stat: done | Score: 10
lib/base64.rb | Pri: medium | Stat: done | Score: 9
A couple of methods are unclear in their purpose, which some better documentation could address.
lib/benchmark.rb | Pri: high | Stat: done | Score: 9.5
Benchmark.benchmark is a bit unclear.
lib/cgi.rb | Pri: high | Stat: done | Score: 10
lib/cgi/session.rb | Pri: high | Stat: done | Score: 9
lib/cgi/session/pstore.rb | Pri: high | Stat: done | Score: 9
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: done | Score: 9
lib/drb/acl.rb | Pri: medium | Stat: open | Score: -
lib/drb/drb.rb | Pri: high | Stat: done | Score: 10
Extremely well documented; but the rest of the drb package remains to be done.
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/ssl.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: done | Score: 9
A few unimportant methods that should perhaps be documented.
lib/eregex.rb | Pri: low | Stat: open | Score: -
Not a serious file.
lib/fileutils.rb | Pri: high | Stat: done | Score: 10
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: done | Score: 9
lib/ftools.rb | Pri: high | Stat: done | Score: 9
One or two methods are hard to explain. Bad variable choices don't help. But it's done.
lib/generator.rb | Pri: | Stat: done | Score: 9
Looks fairly well documented. Needs review.
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: done | Score: 8
Class-level doco is sufficient to grok this, but method doco would be nice as well.
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: 10
All done. Could be better in some way, I suppose, but it's an easy library to understand.
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
A few things to tidy up.
lib/net/http.rb | Pri: high | Stat: done | Score: 9
Some formatting errors.
lib/net/imap.rb | Pri: high | Stat: done | Score: 10
lib/net/pop.rb | Pri: high | Stat: done | Score: 10
lib/net/smtp.rb | Pri: high | Stat: done | Score: 10
lib/net/telnet.rb | Pri: high | Stat: done | Score: 10
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: 6
Good examples, but some cleanup to be done.
lib/open3.rb | Pri: high | Stat: open | Score: -
Not much work to do here.
lib/optparse.rb | Pri: high | Stat: done | Score: 7
Good documentation of OptionParser *class*, not of methods. The latter is not really needed, as the usage example tells you all you need to know. Still, should finish it off at some stage.
lib/ostruct.rb | Pri: high | Stat: done | Score: 10
lib/parsedate.rb | Pri: high | Stat: open | Score: -
Easy.
lib/pathname.rb | Pri: medium | Stat: done | Score: 10
All done. Many methods merely say "See FileTest.xyz", but that doesn't matter.
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: 9
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: done | Score: 9
lib/rdoc/* | Pri: medium | Stat: open | Score: -
Not really relevant to your average stdlib user (certainly not the internals), but we should document the programmatic interface.
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/rinda/rinda.rb | Pri: medium | Stat: open | Score: 5
Methods are documented in two of three classes. Introduction required.
lib/rinda/ring.rb | Pri: medium | Stat: open | Score: -
lib/rinda/tuplespace.rb | Pri: medium | Stat: open | Score: 5
Methods are documented in two of three classes. Introduction required.
lib/rss/* | Pri: high | Stat: open | Score: 1
Nothing more than a link to a tutorial at the moment.
lib/scanf.rb | Pri: high | Stat: open | Score: -
Thoroughly RDed.
lib/set.rb | Pri: high | Stat: done | Score: 10
lib/shell.rb | Pri: medium | Stat: open | Score: -
Nothing there at the moment.
lib/shellwords.rb | Pri: low | Stat: done | Score: 9
lib/singleton.rb | Pri: high | Stat: open | Score: 7
Pretty easy.
lib/soap/* | Pri: | Stat: open | Score: -
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/test/unit.rb | Pri: | Stat: done | Score: 10
lib/test/unit/* | Pri: | Stat: open | Score: -
Must review which files need to be documented.
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: medium | Stat: done | Score: 8
Some improvements possible: background, roadmap, examples; reduce some of the formalism (not all); some English and formatting corrections.
lib/uri/common.rb | Pri: medium | Stat: done | Score: 8
See lib/uri.rb.
lib/uri/ftp.rb | Pri: medium | Stat: done | Score: 8
See lib/uri.rb.
lib/uri/generic.rb | Pri: medium | Stat: done | Score: 8
See lib/uri.rb.
lib/uri/http.rb | Pri: medium | Stat: done | Score: 8
See lib/uri.rb.
lib/uri/https.rb | Pri: medium | Stat: done | Score: 8
See lib/uri.rb.
lib/uri/ldap.rb | Pri: medium | Stat: done | Score: 8
See lib/uri.rb.
lib/uri/mailto.rb | Pri: medium | Stat: done | Score: 8
See lib/uri.rb.
lib/weakref.rb | Pri: high | Stat: open | Score: -
Usage example is there.
lib/webrick.rb | Pri: high | Stat: open | Score: -
lib/webrick/* | Pri: | Stat: open | Score: -
lib/wsdl/* | Pri: high | Stat: open | Score: -
lib/xmlrpc/* | Pri: high | Stat: done | Score: 6
Only a link to the project ('xmlrpc4r') website, which contains full documentation.
lib/xsd/* | Pri: high | Stat: open | Score: -
lib/yaml.rb | Pri: high | Stat: open | Score: -
Should thoroughly document the YAML module.
lib/yaml/* | Pri: | Stat: open | Score: -