문서 작성

크리스탈 문서 주석은 마크다운의 서브셋을 이용합니다.

  • 문서는 클래스, 모듈, 메서드의 바로 위에 위치해야 합니다. 빈 칸이 있어서는 안 됩니다.
  • (역자 주) 이 문서에서는 영어로 문서를 작성하는 법만을 다룹니다.
# A unicorn is a **legendary animal** (see the `Legendary` module) that has been
# described since antiquity as a beast with a large, spiraling horn projecting
# from its forehead.
class Unicorn
end

# 주의: 이 주석은 어떤 클래스에도 붙지 않습니다.

class Legendary
end

  • 메서드의 주석은 메서드 요약과 메서드 상세 내용에 포함됩니다. 요약에는 주석의 첫 줄만이, 상세에는 전체가 포함됩니다. 따라서,

    1. 첫 줄에는 메서드의 목적과 기능을 서술하고
    2. 그 다음에 상세 사항과 쓰임새를 보충하는 것이

선호됩니다. 예시는 다음과 같습니다.

# Returns the number of horns this unicorn has.
#
# ```
# Unicorn.new.horns # => 1
# ```
def horns
  @horns
end

  • 영어로 쓰는 경우 3인칭을 사용하세요. Return the number of horns this unicorn has보다 Returns the number of horns this unicorn has가 좋습니다.

  • 매개변수 이름은 기울여 써야 합니다. (별표 * 또는 밑줄 _ 하나로 둘러싸기)

# Creates a unicorn with the specified number of *horns*.
def initialize(@horns = 1)
  raise "Not a unicorn" if @horns != 1
end
  • 크리스탈 코드를 포함하는 코드 블락은 백틱 세 개로 감싸거나 스페이스 네 개로 들여쓰면 됩니다.
# ```
# unicorn = Unicorn.new
# unicorn.speak
# ```

또는

#     unicorn = Unicorn.new
#     unicorn.speak
  • 프로그램 출력물 등 텍스트 블락을 표현하려면 백틱 세 개와 "text" 예약어를 이용해야 합니다.
# ```text
# "I'm a unicorn"
# ```
  • 다른 타입으로 링크를 걸려면 백틱 하나로 감싸세요.
# the `Legendary` module

  • 현재 문서를 달고 있는 타입의 메서드로 링크를 걸려면 #horns 또는 #index(char)과 같이 우물 정자를 쓰고 백틱으로 감싸세요.

  • 다른 타입의 메서드로 링크를 거는 법은 OtherType#method(arg1, arg2) 또는 OtherType#method와 같습니다.

# Check the number of horns with `#horns`.
# See what a unicorn would say with `Unicorn#speak`.
  • 코드 블락에서 표현식의 값을 나타내려면 #=>를 사용하세요.
1 + 2             # => 3
Unicorn.new.speak # => "I'm a unicorn"
  • 이전 정의와 동일한 주석을 사용하려면 ditto를 이용하세요.
# ditto
def number_of_horns
  horns
end
  • :nodoc:을 통해 생성된 문서로부터 public 선언을 숨길 수 있습니다. private 그리고 protected 메서드는 항상 숨겨져 있습니다.
class Unicorn
  # :nodoc:
  class Helper
  end
end

클래스, 모듈, 메서드에 플래그 달기

유효한 예약어를 지정하면, 문제 사항과 주의점을 강조하는 시각적 플래그가 자동으로 생성됩니다.

지원되는 예약어는 다음과 같습니다.

  • BUG
  • DEPRECATED
  • FIXME
  • NOTE
  • OPTIMIZE
  • TODO

플래그 예약어는 각 줄에서 첫 단어여야 하며 모두 대문자입니다. 예약어 후에 콜론을 붙일 수 있으며, 가독성을 위해 붙이는 쪽이 권장됩니다.

# Makes the unicorn speak to STDOUT
#
# NOTE: Although unicorns don't normally talk, this one is special
# TODO: Check if unicorn is asleep and raise exception if not able to speak
# TODO: Create another `speak` method that takes and prints a string
def speak
  puts "I'm a unicorn"
end

# Makes the unicorn talk to STDOUT
#
# DEPRECATED: Use `speak`
def talk
  puts "I'm a unicorn"
end

크리스탈의 코드 포매터 이용하기

크리스탈에 내장된 코드 포매터를 이용해 코드뿐 아니라 문서 주석에 포함된 예제 코드 또한 포맷할 수 있습니다.

이는 crystal tool format이 호출될 때 현재 디렉토리의 모든 .cr 파일을 포맷하며 자동으로 이루어집니다.

단일 파일을 포맷하는 법은 다음과 같습니다.

$ crystal tool format file.cr

한 디렉토리의 모든 .cr 파일을 포맷하는 법은 다음과 같습니다.

$ crystal tool format src/

이 툴을 이용해 코드 스타일을 통일하고 크리스탈 자체의 문서를 개선할 수 있습니다.

또한 포매터는 빠르기 때문에 파일을 일일히 포맷하는 대신 프로젝트 전채를 포맷하더라도 시간의 손실은 매우 적습니다.

전체 예시

# A unicorn is a **legendary animal** (see the `Legendary` module) that has been
# described since antiquity as a beast with a large, spiraling horn projecting
# from its forehead.
#
# To create a unicorn:
#
# ```
# unicorn = Unicorn.new
# unicorn.speak
# ```
#
# The above produces:
#
# ```text
# "I'm a unicorn"
# ```
#
# Check the number of horns with `#horns`.
class Unicorn
  include Legendary

  # Creates a unicorn with the specified number of *horns*.
  def initialize(@horns = 1)
    raise "Not a unicorn" if @horns != 1
  end

  # Returns the number of horns this unicorn has
  #
  # ```
  # Unicorn.new.horns # => 1
  # ```
  def horns
    @horns
  end

  # ditto
  def number_of_horns
    horns
  end

  # Makes the unicorn speak to STDOUT
  def speak
    puts "I'm a unicorn"
  end

  # :nodoc:
  class Helper
  end
end

문서 생성

프로젝트의 문서를 생성하려면 crystal doc을 호출하세요. doc 디렉토리에 doc/index.html 진입점을 가진 문서가 생성될 것입니다. 프로젝트 루트의 src 디렉토리에 있는 모든 파일이 대상입니다.

results matching ""

    No results matching ""