Docs for Socket, OpenSSL, etc

ruby-talk
21

Hi,

  • rd is being used less and less.

For documenting Ruby code, yes. But it’s still used for other
purposes, for example, writing books and articles. www.ruby-lang.org
and my blog (Japanese) is written in RD, to name a few.

  					matz.

Hmmm… I’ve written a couple of articles and was wondering what might be
a good format to use. Thanks for the tip.

Gavin

···

In message “Re: Ruby Doc Vision (was Re: Docs for Socket, OpenSSL, etc)” > on 03/12/12, Gavin Sinclair gsinclair@soyabean.com.au writes:

22

If one wanted to spent some time documenting a library or extension
(one’s
own, or someone else’s), where would be a good place to look for
documentation on RDoc, and any documentation conventions to be
followed?

For Ruby libraries, you could just have a look at RDoc’s README for
information on how to use it. As for conventions, they’ll be coming
along shortly. I know Gavin’s done some work on the standard library,
but that might have to change a tad if we want to make it work nicely
with ‘ri’ in future. (For example, file-level comments are not
accessible through ri, as files don’t have any meaning at that level.)
Frankly I don’t know the details right now: I’m still learning.

Cheers

Dave

···

On Dec 11, 2003, at 16:36, Derek Lewis wrote:

23

[Derek:]
If one wanted to spent some time documenting a library or extension
(one’s
own, or someone else’s), where would be a good place to look for
documentation on RDoc, and any documentation conventions to be
followed?

[Dave:]
For Ruby libraries, you could just have a look at RDoc’s README for
information on how to use it. As for conventions, they’ll be coming
along shortly. I know Gavin’s done some work on the standard library,
but that might have to change a tad if we want to make it work nicely
with ‘ri’ in future. (For example, file-level comments are not
accessible through ri, as files don’t have any meaning at that level.)
Frankly I don’t know the details right now: I’m still learning.

The way we approach the standard library is this:

  • file-level comments can be used to describe background (e.g. CGI)
  • class-level comments should give a good overview of class
  • method-level comments are snappy (I’ve always kept ri in mind)

That’s not to say we get it right all the time, but I’ll be reviewing
documentation with these in mind.

Derek, the best way to learn some conventions for the standard library is
to look at the existing documentation at RDoc Documentation.
‘cgi’, ‘drb’ and ‘net/*’ are good.

Gavin