Tag certain test methods as being documentation

[Alain Désilets]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200206/4a7d99bd/attachment.htm>