시청

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

  @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

@spec longer_than?(String.t(), non_neg_integer()) :: boolean()
def longer_than?(string, length), do: String.length(string) > length

@spec to_hex({hue :: integer, saturation :: integer, lightness :: integer}) :: String.t()

@type color :: {hue :: integer, saturation :: integer, lightness :: integer}

@spec to_hex(color()) :: String.t()

지침

시청에서 한동안 일하면서, 서류를 작성할 때처럼 일상적인 업무를 빠르게 처리해 주는 도구들을 만들어 왔어요.

그런데 새 동료가 합류하게 되었고, 문득 도구가 그다지 직관적이지 않을 수도 있겠다는 생각이 들었어요. 사무실에는 서류는 항상 대문자로 작성하기, 빈칸은 남기지 않기 같은 이상한 관례가 많거든요.

그래서 새 동료가 곧바로 적응해 도구를 사용할 수 있도록 문서를 좀 써 두기로 했어요.

1. 서식 도구의 목적 문서화하기

Form 모듈에 그 목적을 설명하는 문서를 추가해요. 내용은 다음과 같아요:

A collection of loosely related functions helpful for filling out various forms at the city office.

2. 빈 값으로 필드를 채우는 함수 문서화하기

Form.blanks/1 함수에 문서와 타입스펙을 추가해요. 문서 내용은 다음과 같아요:

Generates a string of a given length.

This string can be used to fill out a form field that is supposed to have no value.
Such fields cannot be left empty because a malicious third party could fill them out with false data.

타입스펙은 이 함수가 음이 아닌 정수 하나를 인자로 받고 문자열을 반환한다는 것을 설명해야 해요.

3. 값을 대문자 배열로 나누는 함수 문서화하기

Form.letters/1 함수에 문서와 타입스펙을 추가해요. 문서 내용은 다음과 같아요:

Splits the string into a list of uppercase letters.

This is needed for form fields that don't offer a single input for the whole string,
but instead require splitting the string into a predefined number of single-letter inputs.

타입스펙은 이 함수가 문자열 하나를 인자로 받고 문자열 배열을 반환한다는 것을 설명해야 해요.

4. 값이 최대 길이의 필드에 맞는지 확인하는 함수 문서화하기

Form.check_length/2 함수에 문서와 타입스펙을 추가해요. 문서 내용은 다음과 같아요:

Checks if the value has no more than the maximum allowed number of letters.

This is needed to check that the values of fields do not exceed the maximum allowed length.
It also tells you by how much the value exceeds the maximum.

타입스펙은 이 함수가 문자열과 음이 아닌 정수, 두 개의 인자를 받고 두 가지 값 중 하나를 반환한다는 것을 설명해야 해요. :ok 아톰을 반환하거나, 첫 번째 원소가 :error 아톰이고 두 번째 원소가 양의 정수인 2-튜플을 반환해요.

5. 서로 다른 주소 형식 문서화하기

알 수 없는 이유에서인지, 시청 내부 시스템은 주소를 나타내는 방식으로 맵과 튜플, 두 가지를 사용해요.

이 사실을 세 개의 사용자 정의 공개 타입을 정의해서 문서화해요:

• address_map - :street, :postal_code, :city 키를 가진 맵이에요. 각 키는 문자열 타입의 값을 담아요.
• address_tuple - street, postal_code, city 세 값을 가진 튜플이에요. 각 값은 문자열 타입이고, 타입스펙에서 이름을 붙여 값들을 서로 구분해요.
• address - address_map 또는 address_tuple이 될 수 있어요.

6. 주소 포맷팅 문서화하기

Form.format_address/1 함수에 문서와 타입스펙을 추가해요. 문서 내용은 다음과 같아요:

Formats the address as an uppercase multiline string.

타입스펙은 이 함수가 주소 하나를 인자로 받고 문자열을 반환한다는 것을 설명해야 해요.