[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
Re: [e4-dev] API-Design Questions
|
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