Tag certain test methods as being documentation

[Jonathan Gibbons]

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