在Elixir中使用ex_doc编写适当的文档

Question

我正在使用ex_doc编写文档，这看起来非常不错，但是我遇到了问题。当一个函数具有一个映射作为参数时，它在文档中被写为“映射”。我想将其显示为“参数”。

示例

def login(conn, %{"email" => email, "password" => password}) do
  ...
end

...在文档中显示为：

login(conn, map)

我知道我可以将函数编写为：

def login(conn, %{"email" => email, "password" => password} = params) do
  ...
end

...获得：

login(conn, params)

...但是通过这种方式，我会收到一个烦人的警告，说“未使用参数”，因为我没有在函数中使用它。

另一个选择是将我的函数写为：

def login(conn, params)
def login(conn, %{"email" => email, "password" => password}) do
  ...
end

...但是我不想编写无用的代码行，只是为了更改文档中的参数名称。有任何想法吗？哪种/正确/最佳/最干净的方式来完成此任务？

更新

按照建议，我尝试使用规格来解决问题。

  @spec login(conn :: %Plug.Conn{}, params :: map()) :: any()
  def login(conn, %{"email" => email, "password" => password}) do
  ...
  end

但这就是我在文档中得到的

login(conn, map)
login(
conn :: %Plug.Conn{
adapter: term(),
assigns: term(),
before_send: term(),
body_params: term(),
cookies: term(),
halted: term(),
host: term(),
method: term(),
owner: term(),
params: term(),
path_info: term(),
path_params: term(),
port: term(),
private: term(),
query_params: term(),
query_string: term(),
remote_ip: term(),
req_cookies: term(),
req_headers: term(),
request_path: term(),
resp_body: term(),
resp_cookies: term(),
resp_headers: term(),
scheme: term(),
script_name: term(),
secret_key_base: term(),
state: term(),
status: term()
},
params :: map()
) :: any()

地图仍然存在，而不是参数，而且我认为在conn结构中显示所有参数不会帮助阅读文档

Answer 1

如果参数名称以_开头，它将从文档输出中删除，并且不会收到未使用的变量警告。以下对我有用：

def login(conn, %{"email" => email, "password" => password} = _params) do
  # ...
end

Answer 2

您应该为函数创建typespecs：

json.NewEncoder(w).Encode("some data")

一旦函数定义为@spec login(conn :: %Plug.Conn{}, params :: map()) :: any() def login(conn, %{"email" => email, "password" => password}) do ... end ，就会从那里自动获取参数名称。

---

边注：：尽管@spec不是强制性的，但任何成熟的Elixir / Erlang代码都应该具有它们。上面建议的方法是正确，不同于将函数子句加倍和/或分配未使用的变量。