针对 `defmethod` 的文档说明不够精确

Question

参数列表

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

文档说明

bq. 为与 dispatch-value 相关的多重方法创建并安装一个新的方法。

这个文档说明存在几个问题，使得理解起来比较困难

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

注：在 clojuredocs.org 中提到方法上允许有可选名称使用 https://docs.clojure.org/clojure.core/defmethod#example-542692c7c026201cdc3269cd，但我没有在哪里看到官方的记录。我不确定这是否得到支持。

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 发布

我改变了主意，我认为最好是只需更改docstring来匹配参数名。

Answer 8

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