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