this question might belong on a more general java list, but since i
came across the issue while doing stuff for collections, you guys are
going to have to suffer ;)
In brief, how should one javadoc when method behaviour differs (or is
more specific) in a subclass, even though that method is not overridden
by the subclass? Or more concretely, if a method which returns a
Collection in a superclass always returns, say, a List in one subclass
and a Set in another subclass, can one cleanly document this fact using
javadoc without overriding the method just to add doc? For example:
public class CollectionOfStuff
{
Collection things;
Stuff( Collection c)
{
this.things = c;
}
/**
* Return a Collection of objects.
*/
public Collection getThings()
{
return things;
}
}
public class SetOfStuff extends CollectionOfStuff
{
SetOfStuff( Set s)
{
super(s);
}
/**
* This method will in fact always return a <b>Set</b> of objects.
*/
public Collection getThings()
{
return (Set) super.getThings();
// typecast for emphasis only
}
}
public class ListOfStuff extends CollectionOfStuff
{
ListOfStuff( List list)
{
super(list);
}
/**
* This method will in fact always return a <b>List</b> of objects.
*/
public Collection getThings()
{
return (List) super.getThings();
// typecast for emphasis only
}
}
Obviously the #getThings implementations in the subclasses do nothing
useful, except generate javadoc. Being that we would really like to
document the behaviour of the subclass, how should we do this? Perhaps
put a note into the class-level doc stating that 'methods x, y, and z
from the superclass will always return this subtype of the method's
stated return type'? Can we do better than this?
- Neil
--- Stephen Colebourne <[EMAIL PROTECTED]> wrote:
> I've sent the author a mail to see what his views are. If he is
> favourable,
> it will require primitive-collections to split from [collections], as
> the
> code balance would be wrong. In fact I think I'm +1 to doing that
> anyway.
>
> The name - [primcoll], [pcollections], [primitive-collections],
> [primitives] ?
>
> Stephen
>
> ----- Original Message -----
> From: "__matthewHawthorne" <[EMAIL PROTECTED]>
> > I took a look around the web for primitive collection
> implementations,
> > http://pcj.sourceforge.net looked interesting, and had some links
> at the
> > bottom to similar projects.
> >
> >
> >
> >
> > On Thu, 2003-08-21 at 16:24, Stephen Colebourne wrote:
> > > At work I use Velocity to generate the java classes which then
> get
> checked
> > > into the CVS. The main trick in my case was to allow the
> generated java
> > > files to be read in again by the generator next time around, so
> manually
> > > added methods weren't lost.
> > >
> > > Code generation will work well for generating primitive Maps as
> there
> are so
> > > many possible combinations. However, before anyone starts, it
> would be
> good
> > > to search the web as I'm sure someone has probably already done
> this.
> They
> > > may be persuedable to donate the code/generator to Apache.
> > >
> > > Stephen
> > >
> > > ----- Original Message -----
> > > From: "J.Pietschmann" <[EMAIL PROTECTED]>
> > > > __matthewHawthorne wrote:
> > > > > There are many times that I've wished I had found a nice way
> to
> > > > > autogenerate things while creating a bunch of redundant
> primitive
> > > > > methods.
> > > >
> > > > There are half a zillion methods for generating code, starting
> > > > with Bash/Sed/Perl hacks, leading to dedicated macro languages
> > > > like the C preprocessor and m4, continuing with a variety of
> web
> > > > templating languages like PHP, there's XSLT and finally high
> > > > level stuff like lex/yacc, ANTLR and all the other grammar
> > > > generators.
> > > >
> > > > The recurrent problems:
> > > > - Need dedicated Ant tasks (Make was a bit easier here)
> > > > - IDEs rarely handle them well
> > > > - Tracking compile and runtime errors caused by generated code
> > > > to the ultimate source isn't well supported and often
> painful
> > > >
> > > > I personally use ad-hoc generators mainly to bootstrap code,
> once
> > > > the bulk of the code is stable, I abandon them.
> > > >
> > > > J.Pietschmann
> > > >
> > > >
> > > >
> ---------------------------------------------------------------------
> > > > To unsubscribe, e-mail:
> [EMAIL PROTECTED]
> > > > For additional commands, e-mail:
> [EMAIL PROTECTED]
> > > >
> > >
> > >
> > >
> ---------------------------------------------------------------------
> > > To unsubscribe, e-mail:
> [EMAIL PROTECTED]
> > > For additional commands, e-mail:
> [EMAIL PROTECTED]
> > >
> >
> >
> ---------------------------------------------------------------------
> > To unsubscribe, e-mail: [EMAIL PROTECTED]
> > For additional commands, e-mail:
> [EMAIL PROTECTED]
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
