6

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?)

Raphael
  • 9,779
  • 5
  • 63
  • 94
RyanWilcox
  • 13,890
  • 1
  • 36
  • 60

2 Answers2

1

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.

Jeff Scott Brown
  • 26,804
  • 2
  • 30
  • 47
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: Screenshot of IntelliJ IDEA quick-doc rendered from above code

Explicitly accessing all args seems to have the benefit of enabling limited syntax completion:
Screenshot of IntelliJ IDEA completing parameters of method example, given a matching prefix
But, alas, the documentation is not displayed (unsurprisingly) No list of possible parameters is provided, either:
Screenshot of IntelliJ IDEA parameter list for method example

Raphael
  • 9,779
  • 5
  • 63
  • 94