Groovydoc: Documenting named parameters

Question

I've created a method like so:

void myMethod(Map kwArgs, def myParam)
{
   println kwArgs.firstName
   println [kwArgs.lastName, "Wilcox"].find()  
   // ^^^ if lastName named parameter not specified, "Wilcox"

   ....
}

Now comes the time to document this method with GroovyDoc. Part of it is easy

/**
  myMethod rules the world
  @param myParam something something

But how do I document the named parameters? (Likewise, how can I specify that the lastName parameter has a default? (ie is there some metadata I can set or just make that explicit to the reader in the English description?)

Answer 1

I have adopted a pattern that uses <dl> in the documentation comment, and re-assignment for clarity (and inspection?):

/**
 * Nothing to see here
 *
 * @param kvargs <dl>
 *     <dt>{@code foo: String}</dt>
 *     <dd>
 *         The root of it all<br />
 *         <em>Default:</em> {@code bar}
 *     </dd>
 *
 *     <dt>{@code baristas: List<String>}</dt>
 *     <dd>
 *         Whom to blame<br />
 *         <em>Default:</em> {@code []}
 *     </dd>
 * </dl>
 */
void example(@Nonnull Map kvargs = [:]) {
    def foo = kvargs.foo?.toString() ?: 'bar'
    def baristas = (kvargs.baristas ?: []) as List<String>

    doThings(foo, baristas)
}

I haven't rendered it as HTML, but the output is good enough in IDEA:

Explicitly accessing all args seems to have the benefit of enabling limited syntax completion:

But, alas, the documentation is not displayed (unsurprisingly) No list of possible parameters is provided, either:

Answer 2

But how do I document the named parameters?

Unless you are considering writing a customer doclet or similar, I think you will just document them as text in the comment.