`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 这里的意思是“可以作为函数传入的附加参数”，这包括函数名称，因此这是支持的。

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)