commons-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gilles (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (MATH-854) Fill the "throws" clause of all methods
Date Fri, 16 Aug 2013 11:23:48 GMT

    [ https://issues.apache.org/jira/browse/MATH-854?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13742107#comment-13742107
] 

Gilles commented on MATH-854:
-----------------------------

Do I conclude correctly that you eventually convinced yourself that unchecked exceptions should
not be included in the signature of methods (but only documented through Javadoc "@throws"
tags)?

At least, you have _proven_ that this issue's description is invalid:
 "[...] by having the "throws" clause of all methods to contain all exceptions possibly thrown
(i.e. also the unchecked ones), it would be possible to ensure that the documentation is complete."
Indeed, in the above (counter-)example, you show that by implementing this issue we would
create either
* correct documentation but _supposedly_ incomplete (since the exception is in the signature
but not documented), or
* complete but wrong documentation (the exception is documented although it will actually
never occur).

IMO, this is more than enough to close the issue.

                
> Fill the "throws" clause of all methods
> ---------------------------------------
>
>                 Key: MATH-854
>                 URL: https://issues.apache.org/jira/browse/MATH-854
>             Project: Commons Math
>          Issue Type: Task
>    Affects Versions: 3.0
>            Reporter: Gilles
>            Priority: Trivial
>             Fix For: 4.0
>
>
> In discussions that led to this [thread|http://markmail.org/message/yu4lrnue54sncbek],
it was concluded that by having the "throws" clause of all methods to contain _all_ exceptions
possibly thrown (i.e. also the unchecked ones), it would be possible to ensure that the documentation
is complete.
> This could be done by *temporarily* switching the base class "MathRuntimeException" (see
MATH-853) to become a _checked_ exception and generating the CheckStyle report which will
detect the mismatch between the Javadoc and the "throws" clause. (Thanks to Luc for this trick.)

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira

Mime
View raw message