They should look at how Dokka does this for Kotlin. It's kind of builds on the same conventions and syntax and plugs into the same infrastructure for deploying documentation along with jar files (i.e. maven). So it use the same @return, @param and so on tags and a few Kotlin specific ones.

Some differences:

- obviously it supports markdown and does the obvious things with that. Particularly using code blocks for examples is nice.

- you can refer to parameters and other things inline, so you don't have to have a separate line for each parameter or the return value but you can write something like "Returns the square root of [myparam]". No need to spell out @return or @param myparam

- it encourages to write short documentation. You don't have to list each parameter for example. If it is obvious from the signature, it won't force you to spell out that the parameter number is indeed an Int. That's a good thing, a lot of Javadoc is just spelling out things that are obvious and skipping all the not so obvious things.

- it has github markdown as an output options. Nice in combination with a static site generator or github sites.