census-instrumentation
Consider testing the code examples contained in Javadocs.
We should test these examples to at least ensure that they compile. I'm not sure what we should use, though. I did a quick search and found one implementation of doctest for Java: https://github.com/jakewins/javadoctest
I found codesnippet4javadoc which might suit our needs better: https://github.com/jtulach/codesnippet4javadoc
It introduces a codesnippet tag to replace the code tag. This new tag can link to a method in which you can write the example. When generating javadoc, this tag will be processed by a customized Doclet to grab the content of the example method. Putting code in actual method ensures it is compilable. Correctness can also be ensured by adding unit test for that method. These methods can be put in other classes so it is easy to write rules be exclude them from output jar.
I've tried the solution and it seems promising.
Code snippets can be defined by wrapping the block with // BEGIN: XXX and // END: XXX and they can be rendered in javadoc by {@codesnippet XXX}.
I've somehow managed to re-organize some javadoc examples. Other examples are incomplete so I just leave them as they are for now.
One big concern is that codesnippet's licence is GPLv3. I am not sure if it is OK even though we do not include or modify the source code.
Confirmed with Gopi that as long as we do not distribute the binary or its derivatives we should be fine with the license.
google-cloud-java invented a script to resolve this issue. The functionality of their tool is pretty the same except that it can inject parameters to add readability. Besides, they also write unit test for the snippets, even though they already have unit tests for the APIs.
I have some initial code example to use codesnippet4javadoc but that it is a little bit outdated. I'll update it and then prepare a PR during my vocation.