[#2367] Standard libraries — Dave Thomas <dave@...>

From ruby-dev summary:

60 messages 2004/02/11

[#2397] PATCH: deprecate cgi-lib, getopts, importenv, parsearg from standard library — Gavin Sinclair <gsinclair@...>

Index: cgi-lib.rb

15 messages 2004/02/12

[#2465] PATCH: OpenStruct#initialize to yield self — Gavin Sinclair <gsinclair@...>

This is a common approach I use to object initialization; I don't know

24 messages 2004/02/19

Re: Standard libraries

From: Dave Thomas <dave@...>
Date: 2004-02-12 20:26:54 UTC
List: ruby-core #2415
On Feb 12, 2004, at 14:01, Sean E. Russell wrote:

> 	class Element
> 		...
> 		def attribute[]( name )
> 		...
> 		def element[]( foo )
> 		...
> 	end
>
> attribute returns... a string value?  Or an Attribute?

I'd personally document the method to say

   # Returns the Value corresponding to _name_.
   def attribute[](name)
   end

I'm not saying yo don't put return types in the documentation. I just 
don't think you need to have big tables containing all the parameters, 
all the possible returns, and so on. I'd recommend using the most 
concise form possible: narrative, combined with meaningful names, works 
most of the time. For the rest, then tables, or other means, should be 
used.

> How this happens, well... we've had this conversation before, and I 
> still
> don't have a good answer.  There are two (as I see it) options:
>
> 1) Put the tests/examples directly in the documentation
> 2) Make RDoc URI aware, and provide relative URLs in the documentation 
> to
> specific test cases, and then have RDoc inline code from the tests.

In that case, why not just use the existing link: syntax?

   # blah blah
   # Tests:  link:test/t1.rb


Cheers

Dave


In This Thread