Re: Standard libraries

On Thursday 12 February 2004 11:54, Dave Thomas wrote:
> Quite often though you can get away with some common sense parameter
> naming.
...
>     def each_person
>        . . .
>        yield name, address_book_entry
>       . . .
>     end

I agree: rdoc is great about extracting this sort of information for users.  
Type is not identified here, though.  Is "name" a Name object, or a String?  
What is the return value for each_person?  You may think that 
"address_book_entry" may be self-explainatory as far as type, but in some 
cases it isn't this clear:
	
	# XML:
	class Element
		...
		def attribute[]( name )
		...
		def element[]( foo )
		...
	end

attribute returns... a string value?  Or an Attribute?  I could have named it 
attribute_value[], but then we're starting to add significantly to the method 
names.  And what is the foo argument for elements()?  Well, maybe it has 
three legal types: a String representation of an XPath, an XPath object, or 
an integer, which is the child index.  I can't think of a good name for "foo" 
that makes it obvious what the type is.

I'm not being difficult -- this isn't uncommon; in Java, we'd be overloading 
the methods, but in Ruby you have to rely on the documentation for type 
constraints.

Most of what I'm talking about has to do with type, and this is specifically 
because of the loose typing of Ruby.  I'm not complaining about loose typing, 
mind you, but I do think that if a language is loosely typed, it pays to be 
careful about documenting what types are legal.


> I was concerned about the security issues of this, and to be frank
> right now I don't have the time to dig deeper in to it. If someone
> wants to come up with a proposal, and eventually some code, I'm game...

Hm.  Ok.  I'll look into it.  I'm not too concerned about security issues.  
I'd say that it would either be a separate tool or an optional argument.   In 
any case, it'd be of more use to developers than users, and if you're 
installing and running somebody else's software, malicious code in the 
documentation is hardly more dangerous than malicious code in the 
sourcefiles.

I believe it is the domain of RDoc because it'd be nice if RDoc was able to do 
something interesting with the code -- use it in the documentation as an 
example, for instance.  That, and since RDoc is parsing the documentation 
anyway... But it could easily be a separate tool.

> FWIW, I think we need to resist the temptation to add too much
> documentation to the files. I agree with Gavin: a section at the top
> explaining intent and usage, and enough information on each public
> method and class to get someone started. Many public methods get a
> single line comment, some get a lot more.

IMO, constraint documentation is important, but examples are even more 
important, and I still believe that having them merged with the API 
documentation that RDoc produces would be a big win.

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.

(2) is more work, but solves the "inline bloat" issue.

Example:

	MyProject/
		tests/
			MyTester.rb
				...
				def test_blah
				...
		source/
			MyClass.rb
				...
				# ... some rdoc documentation
				# %% ../tests/MyTester.rb#test_blah

where "%%" is shorthand for "example URI:", and the "file:" protocol is 
implicit.  RDoc would, in this case, inline the entire method in the 
documentation.  It would be up to the developers to ensure that the method is 
small and clear enough to be useful as an example.


Is what's in the Ruby CVS your current codebase?

-- 
### SER   
### Deutsch|Esperanto|Francaise|Linux|XML|Java|Ruby|Aikido
### http://www.germane-software.com/~ser  jabber.com:ser  ICQ:83578737 
### GPG: http://www.germane-software.com/~ser/Security/ser_public.gpg