Sorry about the timing, Gavin, but I'm in a hurry at the moment and
will address these questions properly tonight. The reality is that
there is no standard. When everything's done we may look at
standardising, but it's pretty obvious what the priority is for now :)
Cheers,
Gavin
On Wednesday, February 25, 2004, 6:29:36 AM, Gavin wrote:
> 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)
|
