Alain,
Thank you for your interest.
I'm not sure I understand completely how you use these methods, but I
agree that it is important to ensure that the example code in
documentation comments is valid code. We are looking at ways to
support that, using new tags in some way that refer to external files
that can be (separately) compiled and tested for validity. I don't think
we would pull in source code from tests; it's more likely we would
introduce a new "path" option (--example-path?) to specify the location
of these files.
-- Jon
On 2/6/20 4:11 AM, Alain Désilets wrote:
One thing I learned about years of programming in Perl is that one of
the best way to document the use of a class is to write a good
synopsis for it:
http://blogs.perl.org/users/neilb/2014/07/give-your-modules-a-good-synopsis.html
As pointed out in this blog post, it's important to make sure that the
code in your synopsis actually works. One trick I have developed ito
that effect is to include a certain number of "documentation tests" in
my test classes. These tests appear at the very beginning of my test
classes, and and are clearly separated from the rest of the tests. For
example, here is the synopsis test I wrote for a class designed to
facilitate capture of STDOUT to a string:
/*********************************
* DOCUMENTATION TESTS
*********************************/
@Test
*public* *void* test__StdoutCapture__Synopsis() {
//
// Use StdoutCapture to temporarily capture System.out to a string
//
StdoutCapture./startCapturing/();
// These will not be printed to Stdout and instead will be stored
// in a string.
//
System.*/out/*.println("Hello World.");
System.*/out/*.println("Take me to your leader.");
// When you stop capturing Stdout, you get a string with everything
// that was printed to it while you were capturing
//
String output = StdoutCapture./stopCapturing/();
}
The problem with this approach is that the the source code of these
documentation tests is only available to people who have access to the
library's source code, which may not always be the case.
I was wondering if there is a way to tag specific methods so that
their source code will be included in the javadoc.
If not, maybe this could be an interesting feature to add?
Thx.
Alain Désilets
