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