번역 : godoc: Tips & Tricks

다음 포스트의 내용을 한글로 옮긴 것입니다 :

http://elliot.land/godoc-tips-tricks by Elliot Chance

go는 처음 공개되었을 때부터 간편하고 실제적인 문서화에 중점을 두고 있다. 형식이 명확하게 정해진 Markdown같은 기존의 포맷을 사용하기보다, godoc은 양질의 문서를 일반 텍스트로부터 뽑아내기 위해 - 문서의 포맷을 맞추는 데 드는 시간을 줄이고, 문서 자체를 작성하는 데 사용하는 시간을 늘리기 위해 - 많은 암시적인 룰을 사용한다.

godoc은 여러가지 포맷으로 문서를 생성할 수 있다. manpage와 같은 텍스트도 가능하지만, 대부분 당신이 볼(마주칠) 것은 HTML 포맷으로 이루어진 버전이다.

여기서는 godoc 커맨드 라인 툴을 사용하는 방법보다. godoc이 formatting을 어떻게 하는 지에 대해 설명한다. godoc 툴 사용법에 대해서는 잘 설명된 문서들이 많다.

Package Overview & License

// Copyright Some Company Corp.
// All Rights Reserved

// Here is where we explain the package.
// Some other stuff.
package doc

패키지-레벨 문서화는 'package’ 구문 이전에 공백없이 이어진 주석으로 이루어져야 한다. ‘package’ 문과 주석 사이에 빈 줄이 있으면 해당 주석은 문서화되지 않는다. 이것을 이용해서 package 문서화에에 포함되어야 할 내용과 그렇지 않은 내용을 구분할 수 있다.

위 예제에서,

// Copyright Some Company Corp.
// All Rights Reserved

부분은 package Overview에 포함되지 않는다.

첫 문장은 자동적으로 추출되어 패키지 리스트에 다음과 같이 패키지에 대한 간략한 설명으로 출력되기 때문에 중요하다.

패키지가 하나 이상의 파일로 이루어질 수 있기 때문에, 패키지에 대한 문서를 여러 파일들에 분산시킬 수 있고, godoc은 그것들을 동일한 Overview block으로 합친다. 합쳐지는 순서는 예상하기 어렵지만, 개별 파일에 패키지의 일부를 문서화하는 좋은 방법이다.

대신에, 코드는 없고 패키지에 대한 완전한 문서와 package 구문만 포함된 파일 을 만들어서 추가할 수 있다.

Paragraphs(단락)

여러 라인들을 쉽게 감싸기 위해 godoc은 뒤따르는 라인을 같은 단락의 포함된 가정할 것이다. 그러나 빈 줄로 단락을 분리할 수 있다.(그러나 같은 블록에 포함된다는 것을 알려주기 위해 //을 넣어야 한다.) Markdown에 익숙하다면, 같은 방식이라는 것을 알 수 있을 것이다.

// Here is where we explain the package.
//
// Some other stuff.
package doc

Constants(상수)

많은 패키지들이 외부로 노출된 상수들을 포함하고 그것들은 잘 문서화되어야 한다. 두 가지 방법이 있는데 첫번째는 모든 각각에 주석을 붙이는 것이다.

// This is the host
const Host = "example.com"

// The port number for the host.
const Port = 1234

관련된 상수들이 있다면 하나의 상수 선언으로 포함하는 것이 더 좋을 것이다.

// This appears under the const.
const (
    // This causes Foo to happen.
    OptionFoo = 1

    // This causes Bar to happen.
    OptionBar = 2

    // Documented, but not visible.
    optionSecret = 3
)

Methods(함수)

// Math stuff.

// Absolute value.
func Abs(x float64) float64 {
}

// Sine value.
func Sin(x float64) float64 {
}

// Internal stuff.

// Docs are important even for internal stuff.
func secretMethod() {
}

주석이 메소드 앞(func 구문 바로 위)에 바로 붙어 있게 해야 한다.(패키지의 경우와 동일) 그렇지 않으면 godoc은 포함하지 않는다.

외부로 노출된 함수들만 문서화에 포함된다. (위 코드에서 secretMethod()는 포함되지 않음)

Headings & Sections

go는 문장처럼 보이는 것을(이거나 그렇지 않아 보이는 것에) 민감하다. godoc은 대문자로 시작하고 마침표로 끝나지 않은 것을 heading으로 인식한다.

// Here is where we explain the package.
//
// See Also
//
// Some other stuff.
package doc

Code Blocks

코드 블록은 코드를 문서화할 수 있게 해 준다. 하나 이상의 스페이스로 시작되는 주석은 code block으로 간주한다.

// This is how to create a Hello World:
//  fmt.Printf("Hello, World")
// Or:
//  fmt.Printf("Hello, " + name)

코드 블록은 컬러링을 사용하지 않지만, 그렇기 때문에 언어와 상관없이 사용할 수 있다.

Links

링크는 자동적으로 인식된다.

// See https://godoc.org for more information.