On Tue, 13 Jan 2015 20:25:53 -0700, Phil Steitz wrote:
On 1/13/15 6:24 PM, Gilles wrote:
Hello.
Now that we can run the code located in the "src/userguide"
directory, I'd propose that some examples be written that
produce various reports for inclusion in the user guide.
A good starting point would be to move
o.a.c.m.util.FastMathTestPerformance
from the "src/test" directory to "src/userguide".
Rationale: it's not really a test but actually a benchmark
that's only useful through _looking_ at the output.
Why does the report itself belong in the user guide? Does it help
users make better decisions about how to use [math]? That is what
the User Guide is for - to help people find things and learn how to
use the software. If the performance tests help make decisions,
then fine; if not they should not be reproduced in the guide. Or
are you just suggesting we move the code there so it is easier to
execute?
A table that quantitatively backs the claim that FastMath is a
faster and more accurate replacement for Math is (IM not so HO)
totally relevant to help users decide whether they should find
and replace every occurrence in their applications.[1]
That said, if you feel strongly that the user guide is not the
best place for something like a "Commons Math Facts" chapter,
we could create another document.
The second reason is practical, indeed: it will be easier to
write and run something there that will produce an appropriately
formatted[2] output without introducing spurious dependencies in
the "test" part of the repository.
Gilles
[1] I know a distinctive case where users passed on it because
some unit tests failed as a result of the change, and no
advantage was prominent enough to warrant investigation.
[2] Suggestions welcome.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
