[jdom-interest] Javadoc suggestion for Element.java

[Jools Enticknap]

On Tue, 13 Jun 2000, Jason Hunter wrote:

> > Here is a short text which I feel might be of use to programmers who
> > might want to subclass Element.
> 
> I took your base and enhanced it a little.  Let me know if you think
> anything needs to be added.  You're right this has the potential to
> cause problems because a simple Element subclass constructor will
> implicitly call super().  If this doesn't take care of people's
> problems, we should add it to the FAQ.  Notice I removed your part about
> "if you can't call a non-default" since it wasn't clear to me when that
> might occur.  Perhaps you could explain.

Concievably you might want to construct the basic Element and perhaps
name it a short time after it has been constructed, say for instance.

Thus it would not be possible to call a "non-default" constructor as
it would throw an exception if you passed a null for the name, simply
because you were going to assign it a value after it had been constructed.

I was 50/50 about the comment when I wrote it, as it's difficult to 
write it without sounding patronising or writing loads of example code
in the javadoc.

I think your modified version is clear and to the point.

--Jools

> 
>     /**
>      * <p>
>      * This protected constructor is provided in order to support an
> Element
>      * subclass that wants full control over variable initialization. 
> It
>      * intentionally leaves all instance variables null, allowing a
>      * lightweight subclass implementation.  The subclass is responsible
> for
>      * ensuring all the get and set methods on Element behave as
> documented.
>      * </p>
>      *
>      * <p>
>      * When implementing an <code>Element</code> subclass which doesn't
>      * require full control over variable initialization, be aware that
>      * simply calling super() (or letting the compiler add the implicit
>      * super() call) will not initialize the instance variables which
> will
>      * cause many of the methods to throw a
>      * <code>{@link NullPointerException>}</code>.  Therefor, the
>      * constructor for these subclasses should call one of the public
>      * constructors so variable initialization is handled automatically.
>      * </p>
>      */
> 
> -jh-
> 
> _______________________________________________
> To control your jdom-interest membership:
> http://lists.denveronline.net/mailman/options/jdom-interest/youraddr@yourhost.com
>