At 8:49 PM -0700 5/31/2000, Raab, Andreas wrote:
>Andrew,
>
>>  The documentation in Smalltalk listBuiltinModules suggests that this
>>  function will list all plugins.
>
>The comment in Smalltalk listBuiltinModules says:
>
>	"Return a list of all builtin modules (e.g., plugins)."
>
>What's wrong with this comment?! Being not a native speaker I might miss
>something here but given the selector and comment never even mention any
>other than builtin modules I don't see a problem ;-)

When I read this, I took "e.g., plugins" to mean that plugins --all 
plugins-- are considered builtin modules, the former not being a term 
with which I am familiar.  I didn't understand why it didn't list the 
plugins.

We (ex-)lawyers are often accused of writing bloated sentences, 
arguably so full of words the sentences cannot be understood.  In 
answer, a mentor of mine suggested that lawyers should not write so 
they can be understood -- they should write so they cannot be 
misunderstood.

I think comments should be written likewise.  Whatever the meaning of 
the quoted  phrase, it should make clear that pluggable primitives 
other than those that are somehow "builtin" are not going to be 
listed.

Of course, all this misses my other question: why not provide a means 
to list plugins other than builtins?
-- 
Andrew C. Greenberg		acg at netwolves.com
V.P. Eng., R&D, 		813.885.2779 (office)
Netwolves Corporation		813.885.2380 (facsimile)
www.netwolves.com