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-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
