Groovydoc：记录命名参数

vq8itlhq 于 2023-03-17 发布在其他

关注(0)|答案(2)|浏览(89)

我创建了一个如下的方法：

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

   ....
}

现在是时候用GroovyDoc记录这个方法了。

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

但是我如何记录命名的参数呢？（同样，我如何指定lastName参数有一个默认值？（即，是否有一些元数据我可以设置或只是在英语描述中向读者显式显示？）

groovy

来源：https://stackoverflow.com/questions/36086274/groovydoc-documenting-named-parameters

2条答案

按热度按时间

dsekswqp1#

但是如何记录命名参数呢？
除非您正在考虑编写客户doclet或类似的文档，否则我认为您只会将它们作为文本记录在评论中。

赞(0）回复(0）举报 2023-03-17

dfddblmv2#

我在文档注解中采用了一个使用<dl>的模式，并为了清晰起见（和检查？）重新分配：

/**
 * 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)
}

我没有将其呈现为HTML，但在IDEA中输出已经足够好了：