@hmkz 씨의 「 바쁜 연구자를 위한 테스트 코드 및 문서 작성 방법

Step 0: 환경 구축

테스트 환경: doctest

Elixir 표준 doctest 매크로를 사용합니다. (후술하기 때문에 여기에서는 아무것도하지 않습니다.

문서 생성 라이브러리: ExDoc

"Using ExDoc with Mix "에 따라 deps에 ex_doc을 추가하고 "mix deps.get"하면됩니다.

샘플 프로젝트

사용법을 살펴보기 위해 샘플 프로젝트를 만들어 둡니다.

$ mix new sample
# 中略
$ cd sample
$ vim mix.exs # ex_docをdepsに追加して
$ mix deps.get

Step 1: 함수 쓰기

산술 함수를 모은 Math 모듈을 만들어 봅시다.

모듈을 만들고,

$ mkdir lib/sample
$ vim lib/sample/math.ex

원하는 함수의 가와만을 만들어 둡니다.

defmodule Sample.Math do
  def add(x, y) do
    :not_implemented
  end
end

Step 2: 문서 쓰기

함수 문서를 작성합니다.
그런 다음 사용 예를 iex>로 시작하는 줄에 결과를 다음 줄에 씁니다. (이것은 나중에 테스트됩니다.

@doc """
# 足し算
addは引数を2つ取り、足し算した結果を返します。

      iex> Sample.Math.add(1,2)
      3
"""
defmodule Sample.Math do
  def add(x, y) do
    :not_implemented
  end
end

Step 3: 테스트하기

대상 모듈을 테스트 대상에 포함하기 위해 test/sample_test.ex에 한 줄 추가하면,

defmodule SampleTest do
  use ExUnit.Case
  doctest Sample
  doctest Sample.Math # 追加行、doctestマクロの後に対象モジュール名を書く

  # 略
end

테스트할 수 있습니다.

$ mix test
Compiling 1 file (.ex)
warning: variable "x" is unused (if the variable is not meant to be used, prefix it with an underscore)
  lib/sample/math.ex:9: Sample.Math.add/2

warning: variable "y" is unused (if the variable is not meant to be used, prefix it with an underscore)
  lib/sample/math.ex:9: Sample.Math.add/2

.

  1) doctest Sample.Math.add/2 (1) (SampleTest)
     test/sample_test.exs:4
     Doctest failed
     doctest:
       iex> Sample.Math.add(1,2)
       3
     code:  Sample.Math.add(1, 2) === 3
     left:  :not_implemented
     right: 3
     stacktrace:
       lib/sample/math.ex:6: Sample.Math (module)

.

Finished in 0.04 seconds
2 doctests, 1 test, 1 failure

함수의 로직이 구현되지 않았기 때문에 문서 사용 예제와 결과가 일치하지 않으며 테스트가 실패했습니다.

Step 4: 구현하기

테스트를 통과하도록 구현합니다.

defmodule Sample.Math do
  @doc """
  # 足し算
  addは引数を2つ取り、足し算した結果を返します。

      iex> Sample.Math.add(1,2)
      3
  """
  def add(x, y) do
    x + y
  end
end

구현이 끝나면 다시 테스트합시다.

$ mix test
Compiling 1 file (.ex)
...

Finished in 0.04 seconds
2 doctests, 1 test, 0 failures

테스트가 통과하게 되었습니다♪

Step 5: 문서 생성

문서의 생성은 "mix docs"로 할 수 있습니다.

$ mix docs
# 中略
Generating docs...
View "html" docs at "doc/index.html"
View "epub" docs at "doc/sample.epub" # epubも出力できるんですね！

브라우저에서 index.html을 열고 해당 모듈을 보면,



깨끗한 문서가 출력되고 있습니다. 네!

참고

doctest를 작성하는 방법은 다음이 도움이됩니다.

@ma2ge 님의 Elixir의 doctest 작성 방법 요약

공식 ExUnit.DocTest

Elixir 문서를 작성하는 방법은 다음을 참조하십시오.

공식 Writing Documentation

이상입니다.

Happy Hacking with Elixir!!