Tips for writing JavaDocs

(Mike Hearn) #1

Hello Corda devs,

As part of the runup to 1.0 I’ve been reviewing our JavaDocs:

Note that although we provide both Java and Kotlin ‘skins’ for the documentation (Kotlin skin here), they’re the same docs generated from the same sources.

Here are some things to watch out for when writing code. When between tasks or when explicitly asked to do this work, please also apply these improvements to existing code:

  • Packages should have a clear role and description for what they do. Please add package-level documentation to docs/, a file which is added in PR 1271. Every package should be documented. Getting us to this state will involve moving some code around because right now packages are kind of ad-hoc and were not that well thought out. When introduce new packages, add docs to describe what it’s for up front, so we can avoid this lack of clarity in future.
  • When documenting a class, use @property syntax rather than @param … the latter documents constructor parameters, but when you have class Foo(val bar: String) bar is both a c’tor parameter and a JavaBean property. Using the right KDoc syntax will ensure your doc shows up for the getter/setter methods too.
  • Make sure type parameters are documented with @param.
  • Top level functions and variables get put, by default, into FileNameKt.class type classes. The Kt suffix is an ugly reminder to Java users that Corda is written in a different language. Instead, put relevant functions (including extension functions) in a companion object and mark them @JvmStatic. This ensures the functions appear in the expected place for Java users. Alternatively use @file:JvmName at the top of the file to give the utility class a better name.
  • Use cd docs; gradle dokkaJavadoc after working to re-gen your javadocs locally, and go inspect the output. This will help you spot markup errors and other ways to polish the docs. Check the Java version first and the Kotlin skin after, because more devs will be reading the JavaDoc skinned version.
  • As the style guide already recommends, avoid docs like /** @returns Returns a foo */. This doesn’t render well because the @returns markup already prints "Returns: " in the doc and it means the method itself has no description. Just plain old /** Returns a foo */ is sufficient.
  • Remember to use @see liberally to create See also hyperlinks to other relevant types.

The JavaDoc skin has a few glitches here and there, we might want to contribute a few improvements to Dokka to polish them a little. I’ve filed a few issues with Dokka upstream.