On 01/15/2013 02:00 PM, Gilles Sadowski wrote: > On Tue, Jan 15, 2013 at 10:01:17AM +0100, Thomas Neidhart wrote: >> On Sun, Jan 13, 2013 at 8:28 PM, Phil Steitz <phil.ste...@gmail.com> wrote: >> >>> I just fixed a couple of errors in the User Guide. There are likely >>> lots more and some whole sections that need to be rewritten. >>> Patches are most welcome. >>> >>> One thing we might want to consider is creating separate test >>> packages for the User Guide examples. While this was not >>> consistently done, we used to lift user guide examples from the unit >>> tests, which made sure the examples actually worked. The problem >>> with that approach is that there is nothing to guarantee that when >>> the unit test gets updated to reflect updates / better practices, >>> the same thing happens in the corresponding User Guide example. It >>> would be more likely for this to happen if we either annotated the >>> test cases including guide examples somehow or separated them into a >>> "userguide" test package. We could do this incrementally, by >>> top-level package for example, as we validate and update the guide. >>> What do you think? >>> >> >> I think a math-samples project / directory / whatever would be quite nice. >> So users could directly try out the examples from the guide without the >> need to copy & paste things from there. > > Actually, what would be great to enforce consistency is to have the examples > of the user guide directly link to the code in the "userguide" part of the > test source repository, where the corresponding code would be marked with > some kind of "anchor" (that would create the anchor to be linked to in the > generated HTML). I've no idea whether that's possible... :-}.
added first sample code in src/test/java/org/apache/commons/math3/userguide: ClusteringExample The example prints results of different clustering algorithms for various datasets, and I plan to include the resulting image in the user guide. Thomas --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
