Download Firefox: WindowsMac OS X
logo       
Google Custom Search
    AddThis Social Bookmark Button

Documentation Consistency (rules): msg#00042

Subject: Documentation Consistency (rules)
I'm seeing various 'standards' applied throughout the builtin library documentation. I'd like some guidance on which way is the 'official' way to do things in each case.

1) Parameters in methods: italicized or not?
I'm seeing parameter names both italicized (e.g. Matrix) and not (e.g. File). Which is it?
        method_name( param1, param2 )
        method_name( <i>param1</i>, <i>param2</i> )


2) Return type indication: -> or =>?
Only currently possible in the C call-seq: documentation, I'm seeing both -> and => used. (e.g. File#chmod vs. File#chardev?)
        method_name( ... ) -> returntype
        method_name( ... ) => returntype
        method_name( ... ) -> <i>returntype</i>
[too bad we can't use &rarr; or &Rarr; ... maybe RDoc could swap these out in the HTML documentation?]


3) Empty parameter list ... ()  or not?
        method_name => returntype
        method_name() => returntype


4) Instance present in instance methods?
        method_name => returntype
        myclass.method_name => returntype

[The latter only being possible within call-seq: calls, again, unless RDoc parsed .rb files and inserted a ClassName.downcase in front of all instance methods.]


5) Describing the parameters: formally or inline?
I'm personally a fan of explicitly describing each parameter at the start of the method documentation, e.g. http://phrogz.net/RubyLibs/rdoc/classes/ValidForm.html#M000054

Should this sort of thing be formally suggested, or is it up to each person to decide if the parameter list warrants being laid out like this vs. just describing it inline, such as Bignum#remainder does? (http://www.ruby-doc.org/docs/rdoc/1.9/classes/Bignum.html#M000841)


--
(-, /\ \/ / /\/
"A foolish consistency is the hobgoblin of little minds."





<Prev in Thread] Current Thread [Next in Thread>