On Friday, September 19, 2003, 5:06:33 PM, Xavier wrote:
> I might find the time to document something, where is the CVS? Do you
> document libraries under lib/ or maybe they have their own maintainers?
> (WEBrick comes to mind). Are there any guidelines for contributors?
Take a look at http://www.rubygarden.org/ruby?DocumentingTheStandardLibraries
We document files under lib/ in the Ruby distribution. You can get
anonymous CVS access to that to keep up with the latest. Some files
have their own maintainers, but if you think it's ripe for
documenting, discuss it on this list.
The best place to start is with the files that have been around for
ages. rational.rb is a simple one to begin with. If you finish it,
post it to this list and I'll check it and commit it. If you become a
regular contributor, I'll arrange CVS commit access (note: I have no
control over this and it can take a bit of time).
Regarding guidelines, there are none at the moment, though I'll
probably work on some soon. For now, take a look at net/ftp.rb and
observe the following:
- code author
- documentation author
- documentation credits
- no real information at the file level; it's deferred to the class
- use of :nodoc:, :startdoc: and :stopdoc: to avoid clutter
- verbose description at the class (Net::FTP level) level, including
examples, major methods
- brief descriptions of attributes
- WRITEME reminder on set_socket
- no documentation of private methods
- documentation comments at EOF
Every file has different documentation needs, though. Some methods are
crying out for examples; some classes have so many methods that a
class-level description of the important ones is helpful. Some
modules have so many classes that a modul-level guide is helpful.
Anyway, just use your common sense and don't worry too much about
getting it perfect; I'll review any submissions you make in detail.
Thanks for any help!
Cheers,
Gavin
|
