`defmethod` 的文档字符串不精确

Question

参数列表

bq. (defmethod multifn dispatch-val & fn-tail)

文档字符串

bq. 构建并向 dispatch-value 关联的 multimethod 安装一个新的方法。

这个文档字符串有几个问题，使得它难以理解

1. {{& fn-tail}} 参数未记录。{{& fn-tail}} 的类型/形状是什么？在参考指南中也没有提及 - https://clojure.org/reference/multimethods
2. 文档字符串和参数列表关于 {{multimethod}} 与 {{multifn}} 的名称冲突。
3. 文档字符串和参数列表关于 {{dispatch-value}} 与 {{dispatch-val}} 的名称冲突。

旁注：在 clojuredocs.org 有提及 optional name 允许在方法中，但我在官方文档中没有看到记录。我不确定它是否支持。请参阅示例。

Answer 1

评论者：alexmiller

fn-tail 这里表示 "作为可以传递给 fn 的额外参数"，因此这是支持的。

Answer 2

评论者：marc

添加补丁

Answer 3

评论者：alexmiller

与其将文档字符串从多方法改为多函数，我更愿意将代码从多函数改为多方法。否则看起来很好。

Answer 4

评论者：marc

添加更新后的补丁，该补丁将参数名称更改为与文档字符串匹配，而不是反过来。

Answer 5

评论者：alexmiller

我更喜欢仅在此处更改 docstring 以匹配 dispatch-val（因此，docstring 更改为与代码匹配）。

Answer 6

评论者：marc

仅更改文档字符串的补丁。

我没有将文档字符串中的 {{multimethod}} 词语改为 {{multifn}}。我认为即使参数未记录，{{multimethod}} 这个名称也更清晰。

请详细说明一下，你为什么想更改文档字符串而不是参数名称，Alex？

Answer 7

评论者：alexmiller

我改变了主意，我觉得最好只更改文档字符串以匹配参数名称。

Answer 8

参考： https://clojure.atlassian.net/browse/CLJ-2212 （由 marc 报告）