문서 에서

문서 소개

Elixir 문서:

• 일급 시민이에요.
• Markdown으로 작성해요.
• 특별한 모듈 속성을 사용해서 추가해요.
• 여러 줄 문자열에는 보통 히어독 문법을 사용해요.

문서화에 사용하는 모듈 속성:

• @moduledoc - 모듈을 설명하고, 모듈의 첫 번째 줄에 나타나요.
• @doc - 함수를 설명하고, 함수의 정의와 타입스펙 바로 위에 나타나요.
• @typedoc - 사용자 정의 타입을 설명하고, 타입 정의 바로 위에 나타나요.

defmodule String do
  @moduledoc """
  Strings in Elixir are UTF-8 encoded binaries.
  """

  @typedoc """
  A UTF-8 encoded binary.
  """
  @type t :: binary

  @doc """
  Converts all characters in the given string to uppercase according to `mode`.

  ## Examples

      iex> String.upcase("abcd")
      "ABCD"

      iex> String.upcase("olá")
      "OLÁ"
  """
  def upcase(string, mode \\ :default)
end

문서와 코드 주석

Elixir는 문서와 코드 주석을 서로 다른 두 가지 개념으로 다뤄요.

문서는 공개 API 사용자와 맺는 명시적인 계약이에요. 여기에는 동료와 미래의 나 자신도 포함돼요. 그 사용자들은 소스 코드에 접근할 수 있을 수도 있고 없을 수도 있어요. 그래서 문서가 코드 사용법을 설명해 줘요.

코드 주석은 소스 코드를 읽는 개발자를 위한 것이에요. 메모를 남기거나, 구현 세부 사항을 설명하거나, 개선할 부분을 표시하는 데 유용해요.

문서는 코드의 공개 API를 설명하기 위한 것이기 때문에, 비공개 함수에 @doc 속성을 추가하려고 하면 컴파일 경고가 발생해요. 비공개 함수를 설명할 때는 대신 코드 주석을 사용해요.

warning: defp do_check_length/2 is private, @doc attribute is always discarded for private functions/macros/types
  lib/form.ex:33: Form.do_check_length/2

문서 활용하기

Elixir 프로젝트의 문서에 접근하는 방법은 다양해요.

hexdocs.pm과 ExDoc

hex.pm은 Elixir와 Erlang의 패키지 저장소예요. hex.pm에 게시된 모든 패키지의 문서는 자동으로 hexdocs.pm에 게시돼요. 여기서는 좋아하는 모든 Elixir 라이브러리의 문서는 물론, Elixir 공식 문서까지 찾을 수 있어요.

hex.pm에 패키지를 게시하지 않고도, Elixir 공식 문서와 똑같이 생긴 문서 웹사이트를 프로젝트를 위해 생성할 수 있어요. 이 작업을 해 주는 도구는 ExDoc이에요. ExDoc은 로컬 파일 시스템에서 열어볼 수 있는 HTML 파일을 만들어 줘요.

ExDoc을 사용할 때 최상의 결과를 얻으려면, 문서 작성에 관한 공식 권장 사항을 따르는 게 좋아요.

h IEx 헬퍼

표준 라이브러리뿐만 아니라 설치한 라이브러리와 Elixir 프로젝트의 문서도 컴퓨터에서 바로 볼 수 있어요.

컴퓨터에 Elixir가 설치되어 있다면, iex 명령을 실행해서 대화형 모드로 사용할 수 있어요. (현재 mix 프로젝트의 소스를 불러오고 싶다면 iex -S mix를 사용해요.)

iex에서 h를 입력한 뒤 스페이스와 모듈 이름 또는 함수 이름을 입력하면, 해당 문서를 읽을 수 있어요.

iex()> h String.upcase/1
# def upcase(string, mode \\ :default)
#
# Converts all characters in the given string to uppercase according to mode.
# (...)

모듈이나 함수 이름을 일부만 입력한 뒤 탭 키를 누르면, 자동 완성 기능을 이용해 사용 가능한 모듈과 함수를 찾아볼 수 있어요.

최신 IDE

Elixir를 지원하는 많은 최신 IDE는 문서와 타입스펙을 분석해서 유용한 팝업으로 보여줄 수 있어요. 예를 들어 Visual Studio Code나 Elixir 플러그인을 사용하는 Intellij가 있어요.

내부 모듈과 함수

모듈이나 함수가 내부에서만 사용하도록 만들어졌다면, @moduledoc false나 @doc false로 표시할 수 있어요. 그런 모듈과 함수는 생성된 문서에 포함되지 않아요. 다만 이것이 비공개로 만들어 주는 것은 아니에요. 여전히 호출하거나 가져올 수 있어요. 이 문제를 해결할 수 있는 방법은 내부 모듈과 함수 숨기기에 관한 공식 문서를 확인해 봐요.