On Sunday, November 28, 2010 12:25:22 pm Diego Virasoro wrote:
> Thank you for a very exhaustive reply. Much appreciated. :)
> 
> Just to explain what I meant a bit more clearly, I don't have a
> problem with someone who feels like snooping and modifying things: as
> you point out this is Ruby. I simply meant that I would want him/her
> not to encounter the class in everyday work.

I'm not sure how they would, anyway. After all...

> I can use :nodoc: to remove it from the documentation, but it would
> still be way to easy to encounter.

I think if you've got a number of classes which are actually well-documented, 
and this one isn't, you never instantiate it, your unit tests never 
instantiate it, and it's clearly a base class for other things you _do_ 
provide, it seems like if the user instantiates it, they get to keep both 
pieces.

And it may well be that you want users to discover this class, that you want 
to document common behaviors of subclasses here, but you want to make it clear 
that they should be instantiating subclasses if anything. For instance, 
Nokogiri has this:

http://nokogiri.org/Nokogiri/XML/Node.html

I can't think of any case where it makes sense to instantiate this class 
directly, as opposed to, say, Element or Text. However, it's not hidden, nor 
(as far as I can tell) is there anything preventing me from doing so.

So my recommendation is still to just be clear what it is and what it's for, 
or at the very least that it's not for the end-user. Enforcing the abstract-
ness of something that's clearly abstract smells a bit to me like the kind of 
"safety" you'd get with strict type-checking.

But if you still want to use my pseudo-solutions, happy to help, I guess...