如何为Elixir的defp私有函数编写文档？解决@doc警告问题

问题场景 #

使用@doc为Elixir私有函数添加文档时，VSCode编译器弹出如下警告：

defp check_subscript!/3 is private, @doc attribute is always discarded for private functions/macros/typesElixir

对应的私有函数代码如下：

@doc """
check subscript decreasing or increasing
"""
defp check_subscript!(x, x1, x2)
     when x > x1 and x1 > x2 and
            is_integer(x) and is_integer(x1) and is_integer(x2) do
  :ok
end

Elixir中并不存在@docp这类专门用于私有函数的文档注解，请问该如何正确为defp函数编写文档？

解决方案 #

Elixir官方没有提供@docp注解，针对私有函数的文档编写，有两种常用的正确方式：

方式一：使用普通代码注释 #

直接在私有函数上方用#添加单行或多行注释，这是最简单直接的方式，适合团队内部代码阅读：

# 检查下标是否递减
defp check_subscript!(x, x1, x2)
     when x > x1 and x1 > x2 and
            is_integer(x) and is_integer(x1) and is_integer(x2) do
  :ok
end

方式二：结合@doc与@private属性 #

如果希望私有函数的文档能被ExDoc等文档工具识别为内部文档（但不对外公开），可以在@doc后添加@private属性，这样既不会触发编译器警告，又能保留文档信息：

@doc """
检查下标是否递减或递增
"""
@private
defp check_subscript!(x, x1, x2)
     when x > x1 and x1 > x2 and
            is_integer(x) and is_integer(x1) and is_integer(x2) do
  :ok
end

需要注意的是，第二种方式的文档仅会出现在模块的内部文档中，外部用户通过h命令或公开文档页面无法查看。

内容的提问来源于stack exchange，提问作者Chen Yu