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

Question

arglist

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

文档字符串

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

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

1. {{& fn-tail}} 参数没有文档。{{& fn-tail}} 的类型/形状是什么？在参考指南中也没有提到 - https://clojure.org/reference/multimethods
2. 文档字符串和 arglist 关于 {{multimethod}} 和 {{multifn}} 的名称存在冲突。
3. 文档字符串和 arglist 关于 {{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

我更愿意在这里只更改用于分发值（dispatch-val）的文档字符串（因此文档字符串改为与代码匹配）。

Answer 6

评论由：marc

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

我没有在文档字符串中将“{{multimethod}}”更改为“{{multifn}}”。我相信即使参数没有文档说明，名称“{{multimethod}}”也更清晰。

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

Answer 7

评论由：alexmiller

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

Answer 8

参考： pointing to "https://clojure.atlassian.net/browse/CLJ-2212" (由 marc 报告)