Re: Documentation guidlines (Was: 2nd try at date/format.rb & pty.c)

On Aug 20, 2006, at 4:39 AM, Eric Hodel wrote:

> On Aug 19, 2006, at 5:46 PM, Eric Hodel wrote:
>> On Aug 19, 2006, at 4:14 PM, James Britt wrote:
>>> I'm unaware of  any mention of  "give it a whirl" on ruby- 
>>> doc.org, but I get the point.  If someone has some good  
>>> guidelines for people willing to write docs I'll put them up on  
>>> ruby-doc.org.
>>
>> Here's a start:
>>
>> * Documentation wrapped to 80 characters
>> * Use :: and # for describing methods, . for example code
>> * C methods must have call-seq
>
> Also, the 'submit to Gavin Sinclair' should be switched to 'submit  
> to the ruby-doc mailing list'.

Gavin also suggested the following when I first posted:

* All documentation should be in full sentences ending in a period.
* Separate the documentation from the comment character by one space.

 From what Eric said (correct me if I'm off here):
* code should be indented 2 spaces in from the surrounding text and  
placed in <code></code> blocks.

Is there a policy on the placement of the <code> tags?  Should they  
be on their own lines?  Would the policy change for an example that  
was only one line?

example:
   <code>one.line.example</code>

   <code>
     two.line
     example
    </code>

Any official ruling?

-Mat