Elixir 作為注釋

Elixir從Erlang中得到模塊屬性的概念.例如:

defmodule MyServer do
  @vsn 2
end

在上述例子中,我們精確地設(shè)置了此模塊的版本屬性.?@vsn?由Erlang VM中的代碼重載機(jī)制用于檢查模塊是否被更新.如果沒(méi)有指定版本,版本會(huì)被設(shè)置為該模塊函數(shù)的MD5校驗(yàn)碼.

Elixir由少數(shù)的保留屬性.這里是其中最常用的一些:

• ?@moduledoc?--提供當(dāng)前模塊的文檔.
• ?@doc?--提供該屬性之后的函數(shù)或宏的文檔.
• ?@behaviour?--(注意英式拼寫(xiě))用于指定OTP或用戶(hù)定義的行為.
• ?@before_compile?--提供一個(gè)會(huì)在模塊編譯之前導(dǎo)入的鉤子.這使得在編譯前精確注入函數(shù)到模塊中成為可能.

@moduledoc和@doc是最常用的屬性,我們希望你能經(jīng)常使用它們.Elixir將文檔放在第一類(lèi),并提供了許多訪(fǎng)問(wèn)文檔的函數(shù).你可以在我們的官方文檔中閱讀更多關(guān)于如何在Elixir中書(shū)寫(xiě)文檔.

讓我們回到在之前的章節(jié)中定義了的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來(lái)書(shū)寫(xiě)可讀性強(qiáng)的文檔.Heredocs是多行的字符串,它們由三個(gè)雙引號(hào)開(kāi)始和結(jié)束,會(huì)保存其中文本的格式.我們可以直接從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
...

我們也提供一個(gè)名為ExDoc的工具,它可以用文檔生成HTML頁(yè)面.

你可以在Module的文檔中找到完整的屬性列表.Elixir也用屬性來(lái)定義類(lèi)型規(guī)格.

本節(jié)覆蓋了內(nèi)置屬性.然而,屬性也可以被開(kāi)發(fā)者使用,或是由庫(kù)來(lái)擴(kuò)展,以支持自定義的行為.