Elixir 作为注释

Elixir从Erlang中得到模块属性的概念.例如:

defmodule MyServer do
  @vsn 2
end

在上述例子中,我们精确地设置了此模块的版本属性.​@vsn​由Erlang VM中的代码重载机制用于检查模块是否被更新.如果没有指定版本,版本会被设置为该模块函数的MD5校验码.

Elixir由少数的保留属性.这里是其中最常用的一些:

• ​@moduledoc​--提供当前模块的文档.
• ​@doc​--提供该属性之后的函数或宏的文档.
• ​@behaviour​--(注意英式拼写)用于指定OTP或用户定义的行为.
• ​@before_compile​--提供一个会在模块编译之前导入的钩子.这使得在编译前精确注入函数到模块中成为可能.

@moduledoc和@doc是最常用的属性,我们希望你能经常使用它们.Elixir将文档放在第一类,并提供了许多访问文档的函数.你可以在我们的官方文档中阅读更多关于如何在Elixir中书写文档.

让我们回到在之前的章节中定义了的Math模块,添加一些文档并保存到math.ex文件:

defmodule Math do
  @moduledoc """
  Provides math-related functions.

  ## Examples

      iex> Math.sum(1, 2)
      3

  """

  @doc """
  Calculates the sum of two numbers.
  """
  def sum(a, b), do: a + b
end

Elixir建议使用heredocs的markdown来书写可读性强的文档.Heredocs是多行的字符串,它们由三个双引号开始和结束,会保存其中文本的格式.我们可以直接从IEx获取任何编译好的模块的文档:

$ elixirc math.ex
$ iex

iex> h Math # Access the docs for the module Math
...
iex> h Math.sum # Access the docs for the sum function
...

我们也提供一个名为ExDoc的工具,它可以用文档生成HTML页面.

你可以在Module的文档中找到完整的属性列表.Elixir也用属性来定义类型规格.

本节覆盖了内置属性.然而,属性也可以被开发者使用,或是由库来扩展,以支持自定义的行为.