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

Question

我正在用 ex_doc 写文档，看起来很不错，但我有一个问题。当一个函数有一个映射作为参数时，它在文档中被写成 "map" 。我想将其显示为 "params".

例子

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)

...但是这样我会收到一个烦人的警告说 "params is unused"，因为我没有在我的函数中使用它。

另一种选择是将我的函数写成：

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

...但我不想编写一行无用的代码来更改文档中的参数名称。有任何想法吗？ proper/best/cleanest 实现此目的的方法是哪一种？

更新

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

  @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()

map 仍然存在，而不是参数，而且我不认为在 conn 结构中显示所有参数将有助于阅读文档

Answer 1

您应该为您的函数创建 typespecs：

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

一旦函数定义了 @spec，参数名称将自动从那里获取。

旁注： 虽然 @spec 不是强制性的，但任何成熟的 Elixir/Erlang 代码都应该有它们。上面建议的方法是正确，不像加倍函数子句and/or分配未使用的变量..

Answer 2

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

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

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

Write proper documentation with ex_doc in Elixir

documentation

elixir

phoenix-framework

ex-doc

例子

更新