Hi Sébastien. > 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).
I don't understand why you suggest to not use "@throws" tags. All (non-trivial) exceptions must be documented. The Javadoc "@throws" is especially useful for advertising _unchecked_ exception. [In some sense, "@throws" tags are redundant for checked exceptions, because those are detected by the parser/compiler and their existence can be advertised automatically.] Checkstyle indeed does not complain if an unchecked exception is documented but does not appear in the signature of a method. I think that the rules stated in "Effective Java" are simple and consistent. Best, Gilles --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
