Re: [e4-dev] API-Design Questions

[Francis Upton <francisu@xxxxxxxx>]

I agree with IAE, but I don't think it needs to be in the Javadoc, and I think there should be a convention that null is generally not allowed, unless it specifically means something.  I like the way the XSD (in EMF) stuff simple does not allow nulls, and if you want something semantically empty, I think they use a special class indicating a null value which removes special checking everywhere.

IAE should be able to be thrown at any time if the arguments are not valid for whatever reason.  And since this is a RuntimeException, I think the general convention is these are not Javadoced (unless there is something very special about it).

On Wed, Mar 10, 2010 at 2:09 PM, Tom Schindl <tom.schindl@xxxxxxxxxxxxxxx> wrote:

Hi,

I've added a new method today to the EPartService which has the
following JavaDoc

-----------8<-----------
> /**
>        * Returns a collection of all {@link MInputPart} with the inputURI-Attribute set to the given
>        * value
>        *
>        * @param inputUri
>        *            the input uri to search for, must not be <code>null</code>
>        * @return list of parts or an empty collection
>        */
>       public Collection<MInputPart> getInputParts(String inputUri);
-----------8<-----------

As you'll see the method specs that NULL is not an allowed value. Now I
think we should define what writing methods like this means.

Question: Should it throw a RuntimeException?

Question: if yes which one:
 * IllegalArgumentException
 * org.eclipse.core.runtime.AssertionFailedException
 * NullPointerException

Question: and should it be document in the JavaDoc like this:
-----------8<-----------
> /**
>        * Returns a collection of all {@link MInputPart} with the inputURI-Attribute set to the given
>        * value
>        *
>        * @param inputUri
>        *            the input uri to search for, must not be <code>null</code>
>        * @return list of parts or an empty collection
>        * @throws IllegalArgumentException
>        *             if null passed as argument
>        */
>       public Collection<MInputPart> getInputParts(String inputUri);
-----------8<-----------

My proposal is that we define that we throw an IAE (because then the API
uses standard JDK-Classes) and document it in the JavaDoc.

Tom

--
B e s t S o l u t i o n . a t                        EDV Systemhaus GmbH
------------------------------------------------------------------------
tom schindl                                        geschaeftsfuehrer/CEO
------------------------------------------------------------------------
eduard-bodem-gasse 5/1    A-6020 innsbruck      phone    ++43 512 935834
_______________________________________________
e4-dev mailing list
e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/e4-dev