commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From robert burrell donkin <robertburrelldon...@blueyonder.co.uk>
Subject Re: Subject: [collections][lang] question on javadoc guidelines wrt subclass behaviour
Date Sun, 24 Aug 2003 12:22:34 GMT
IMHO

1. if these changes are implementation details then it's reasonable not to 
document them. rationale: if the contract for the subclass method says 
that the collection will return a set (even though the return type is 
collection) then users may reasonably cast the result to a set. if this is 
an implementation detail then changing this will break a lot of code that 
depends on it.

2. if these changes are not implementation detail but are core features of 
the subclasses then it's reasonable to include these comments in the class 
level documentation of each sub class.

- robert

On Sunday, August 24, 2003, at 09:23 AM, Stephen Colebourne wrote:

> 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" <neilotoole@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 <scolebourne@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" <mhawthorne@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" <j3322ptm@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
>


Mime
View raw message