Author: psteitz
Date: Tue Feb 1 00:23:48 2011
New Revision: 1065874
URL: http://svn.apache.org/viewvc?rev=1065874&view=rev
Log:
Added section on Exceptions.
Modified:
commons/proper/math/trunk/src/site/xdoc/developers.xml
Modified: commons/proper/math/trunk/src/site/xdoc/developers.xml
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/developers.xml?rev=1065874&r1=1065873&r2=1065874&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/developers.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/developers.xml Tue Feb 1 00:23:48
2011
@@ -183,6 +183,50 @@
Guide.</li>
</ul>
</subsection>
+ <subsection name='Exceptions'>
+ <ul>
+ <li>
+ Exceptions generated by Commons Math are all unchecked.</li>
+ <li>
+ All public methods advertise all exceptions that they can generate.
+ Exceptions <i>must</i> be documented in both javadoc and method
signatures
+ and the documentation in the javadoc <i>must</i> include full description
+ of the conditions under which exceptions are thrown.</li>
+ <li>
+ All exceptions inherit from the base class, MathRuntimeException.</li>
+ <li>
+ Methods <i>should</i> fully specify parameter preconditions required for
+ successful activation. When preconditions are violated, a
+ MathIllegalArgumentException should be thrown. Subclasses of
+ MathIllegalArgumentException may be used to represent common parameter
+ contract violations (for example, NoBracketingException). Exception
+ messages <i>must</i> contain sufficient information on parameter values
to
+ determine the exact precondition failure.</li>
+ <li>
+ Exceptions generated by Commons Math make sense without knowing
+ implementation details other than those stated in the public API.
+ For example, a NoBracketingException makes sense thrown by a solver that
+ has a precondition requiring that initial points bracket a root. This
+ exception does not make sense, however, thrown by an inverse cumulative
+ probability estimator.</li>
+ <li>
+ MathIllegalArgumentException should only be thrown in situations
+ where preconditions can be exhaustively provided so that what arguments
+ are "illegal" can be specified fully to the caller. Domain-specific
+ exceptions need to be defined for cases where failures cannot be
+ attributed to parameter precondition violation. For example, the exact
+ domain of successful activation of a solver or quadrature method may be
+ impossible to specify because of numerical properties of the method.
+ If a solver fails to find a root or a quadrature method fails to converge
+ for a given set of parameters, <i>unless those parameters violate the
+ advertised preconditions</i> it is not appropriate to throw
+ MathIllegalArgumentException.</li>
+ <li>
+ State information included in exception messages <i>must</i> be available
+ in exception properties - i.e., successful handling or reporting of
+ Commons Math exceptions must not require parsing exception messages.</li>
+ </ul>
+ </subsection>
<subsection name='Unit Tests'>
<ul>
<li>
