I don't know of any way other than you suggest:
1) Polute the superclass javadoc
2) Add unrequired method to subclass
We need a third option, but that involves javadoc changes.
Stephen
----- Original Message -----
From: "Neil O'Toole" <[EMAIL PROTECTED]>
> 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]
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
