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

On Aug 20, 2006, at 8:07 AM, Mat Schaffer wrote:
> 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?

You don't use <code>.  Lines indented two spaces are turned into a  
code block by RDoc.

class Dummy

   # The boopy_doop method does the thing with the stuff.  It returns  
this
   # thingy when the planets are aligned, and that thingy when the  
portal is
   # open.
   #
   # Example:
   #
   #  obj.boopy_doop(blarg)
   #
   # or:
   #
   #  x = obj.boopy_doop(1, 2, 3)
   #  x.flargl

   def boopy_doop(*args)
   end

end

-- 
Eric Hodel - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com