commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Luc Maisonobe <Luc.Maison...@free.fr>
Subject Re: svn commit: r1230906 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math/random: RandomData.java RandomDataImpl.java
Date Sun, 15 Jan 2012 10:42:17 GMT
Le 15/01/2012 10:26, Sébastien Brisard a écrit :
> Hello Luc and Gilles,
> thank you for taking part in this discussion.
>>
>> Hi Sébastien,
>>
>>>
>>>>
>>>> I used to do that when we still had a single root hierarchy. Changing
>>>> the root temporarily to checked was a simple and efficient way to make
>>>> sure javadoc was OK.
>>>> Now we have removed the single root and this has become a nightmare to
>>>> maintain as every single exception has to be temporarily changed to
>>>> checked in order to do this bookkeeping. This is impossible to do.
>>>>
>>>> As Throwable, Exception and RuntimeException are all classes and not
>>>> interfaces, we can even not declare some intermediate MathThrowable
>>>> interface that would extend RuntimeException in production distribution
>>>> and could be changed to extend Exception in developers works spaces to
>>>> ensure javadoc and throws statements are up to date. I sincerely regret
>>>> this.
>>>>
>>>> Luc
>>>>
>>> what I did in r1230906 was
>>> 1. make sure that exceptions actually thrown in RandomDataImpl are
>>> identical with the @throws clause in the Javadoc of RandomData.
>>> 2. add the unchecked exceptions to the methods signatures.
>>
>> Good, thanks.
>>
>>>
>>> >From what I understand, all exceptions should remain in the javadoc,
>>> right?
>>
>> I think so, but it is only *my* opinion. For now, we let everybody do as
>> they want.
>>
>>> As for methods signatures, I should probably get rid of the
>>> throws in the interface RandomData. How about RandomDataImpl? Would
>>> you rather have the exceptions in the method signature, or not?
>>
>> I'm not sure either. People will look at the interface documentation, so
>> the javadoc here could notify about the exceptions if you feel inclined
>> to put them here. In all cases, it is better to have javadoc and throws
>> clause consistent (I think checkstyle may complain otherwise, depending
>> on its settings about checked/unchecked).
>>
>>>
>>> Thanks for your advice, and I promise I'll clean up my mess ASAP.
>>
>> Don't worry, you did not put any mess here. We (and especially I) put it
>> by ourselves ;-)
>>
>> Luc
>>
> So, are you both happy if I leave this commit "as is"?

Yes.

> 
> An alternative would be to document unchecked exceptions in the
> javadoc, but not in @throws tags. Something along the lines "this
> method should throw/throws an XXXException if...". This way, we would
> be able to remove the exceptions from the method signature if we feel
> that it would be better, and checkstyle would not complain (although I
> actually don't think it does with the current settings).
> I do not have any preference, here. However, I do like the fact that
> unchecked exceptions *are* somehow documented, just to remind me what
> preconditions I should check (as a user).

If this is fine with you, then it is good for me.

Luc

> Sébastien
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message