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 → or ↠ ... 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."
|