RE: Subject: [collections][lang] question on javadoc guidelines w rt subclass behaviour

[Gary Gregory <gg...@seagullsw.com>]

Inline...

> -----Original Message-----
> From: Stephen Colebourne [mailto:scolebourne@btopenworld.com]
> Sent: Sunday, August 24, 2003 01:24
> To: Jakarta Commons Developers List; neilotoole@users.sourceforge.net
> Subject: Re: Subject: [collections][lang] question on javadoc guidelines
> wrt subclass behaviour
> 
> I don't know of any way other than you suggest:
> 1) Polute the superclass javadoc

More Javadoc than not enough is ok by me. The subclass class comment can
make clear that it operates on a Set or other kind of Collection. You can
@see methods from the class comment I suppose to make this clear.

> 2) Add unrequired method to subclass

-1 on that one from me. Adding code just to get Javadocs does smell bad IMO.

> 
> We need a third option, but that involves javadoc changes.
> 
> Stephen
> 
> ----- Original Message -----
> From: "Neil O'Toole" <ne...@users.sourceforge.net>
> > 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 <sc...@btopenworld.com> 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" <mh...@alumni.pitt.edu>
> > > > 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" <j3...@yahoo.de>
> > > > > > __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:
> > > commons-dev-unsubscribe@jakarta.apache.org
> > > > > > For additional commands, e-mail:
> > > commons-dev-help@jakarta.apache.org
> > > > > >
> > > > >
> > > > >
> > > > >
> > > ---------------------------------------------------------------------
> > > > > To unsubscribe, e-mail:
> > > commons-dev-unsubscribe@jakarta.apache.org
> > > > > For additional commands, e-mail:
> > > commons-dev-help@jakarta.apache.org
> > > > >
> > > >
> > > >
> > > ---------------------------------------------------------------------
> > > > To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> > > > For additional commands, e-mail:
> > > commons-dev-help@jakarta.apache.org
> > > >
> > >
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> > > For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> > >
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> > For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> >
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org