From: "Sean E. Russell" <ser@...>
Date: 2004-02-13T05:01:53+09:00
Subject: Re: Standard libraries


--Boundary-02=_pu9KAkDptXY4VM0
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

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

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

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

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

Most of what I'm talking about has to do with type, and this is specificall=
y=20
because of the loose typing of Ruby.  I'm not complaining about loose typin=
g,=20
mind you, but I do think that if a language is loosely typed, it pays to be=
=20
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. =
=20
I'd say that it would either be a separate tool or an optional argument.   =
In=20
any case, it'd be of more use to developers than users, and if you're=20
installing and running somebody else's software, malicious code in the=20
documentation is hardly more dangerous than malicious code in the=20
sourcefiles.

I believe it is the domain of RDoc because it'd be nice if RDoc was able to=
 do=20
something interesting with the code -- use it in the documentation as an=20
example, for instance.  That, and since RDoc is parsing the documentation=20
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=20
important, and I still believe that having them merged with the API=20
documentation that RDoc produces would be a big win.

How this happens, well... we've had this conversation before, and I still=20
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=20
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=20
implicit.  RDoc would, in this case, inline the entire method in the=20
documentation.  It would be up to the developers to ensure that the method =
is=20
small and clear enough to be useful as an example.


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

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

--Boundary-02=_pu9KAkDptXY4VM0
Content-Type: application/pgp-signature
Content-Description: signature

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)

iD8DBQBAK9upP0KxygnleI8RAoFnAKCOtyIe49lsFc0OnQmoP8x8vUnUnQCfcWWH
an6G8gfTRgRUBqwz/xPRGzY=
=28tE
-----END PGP SIGNATURE-----

--Boundary-02=_pu9KAkDptXY4VM0--