원문 : Godoc: documenting Go code ( https://blog.golang.org/godoc )
전체 내용은 원문에서 확인하실 수 있으며, 또 내용 중 일부 오역이 포함되어 있을 수 있으니, 가능하면 원문을 참조하시는 걸 추천드립니다.
Go 프로젝트는 문서화를 중요하게 여깁니다. 문서화는 소프트웨어를 유지보수가능하고 접근성이 좋게 만드는 중요한 부분입니다. 물론 정확하고 잘 쓰여지는 것은 중요합니다. 하지만 작성하고 유지하는 것 또한 중요합니다. 이상 적인 것은 코드와 더불어 계속해서 동시에 변화해나가는 것입니다. 개발자가 문서를 쉽게 만들 수록 모두에게 좋습니다.
이를 위해 godoc이라는 문서화 도구를 만들었습니다. 이 글은 godoc이 문서화를 위해 어떤 방식을 사용했는지 설명합니다. 그리고 문서를 작성하기 위해 규칙과 도구를 어떻게 사용해야 하는지 설명합니다.
godoc은 주석을 포함한 소스코드를 분석하고 HTML이나 일반 텍스트로 문서를 만듭니다. 최종 결과는 코드와 밀접하게 연관된 문서입니다. 예를 들어 godoc의 웹 인터페이스를 통해 한번의 클릭으로 함수의 문서를 탐색할 수 있습니다.
godoc은 개념적으로 파이썬의 Docstring과 자바의 javadoc과 관련되지만, 더 간략하게 설계되었습니다. godoc이 인식하는 주석은 (Docstring처럼) 언어적 구조를 갖추지 않으며, (자바처럼) 기계가 인식할만한 구조를 가지지도 않습니다. godoc 주석은 그냥 좋은 주석이며, godoc이 없더라도 읽고 싶은 종류의 주석입니다.
규칙은 간단합니다. 유형, 변수, 상수, 함수, 또는 패키지를 문서화하려면 일반적인 주석을 선언하는 곳의 빈줄 없이 바로 앞에 적어줍니다. 그러면 godoc은 해당 주석을 문서화하여 보여줍니다. 다음 예시는 fmt 패키지의 Fprint 함수의 문서화 입니다.
// Fprint formats using the default formats for its operands and writes to w.
// Spaces are added between operands when neither is a string.
// It returns the number of bytes written and any write error encountered.
func Fprint(w io.Writer, a ...interface{}) (n int, err error) {커멘트는 설명하고자하는 요소의 이름으로 시작하는 완전한 문장이어야 함을 알아야 합니다. 이건 일반적인 문장에서 HTML로 만들거나 Unix man 페이지로 만들 듯이 다양한 형식으로 문서를 만들 수 있게하는 중요한 규칙입니다. 문장의 첫줄이나 문장을 추출하는 축약을 할 때, 더 의미를 파악하기 쉽게 해줍니다.
패키지 선언에서 주석은 일반 적인 패키지 문서화를 합니다. sort 패키지의 간결한 주석처럼, 짧을 수 있습니다.
// Package sort provides primitives for sorting slices and user-defined
// collections.
package sortgob패키지의 개요처럼 상세하게 적을 수도 있습니다. 설명할 문서의 양이 많은 패키지를 위한 다른 규칙을 사용할 수 있습니다. 패키지 주석을 패키지 구문과 주석만을 담은 doc.go 같이 별도의 파일에 적을 수 있습니다.
많은 양의 패키지 주석을 쓰더라도 첫 문장이 godoc이 만든 문서의 맨 처음 나타난다는 것을 알아두세요.
맨처음 선언한 주석의 근처에 있지 않으면, 한가지 예외를 제외하고, godoc의 출력에서 제외 됩니다. "BUG(who)"라고 시작하는 주석은 버그로 인식되고 패키지 문서에 "Bugs" 영역에 포함됩니다. "who"는 반드시 더 많은 정보를 제공할 누군가가 적혀야 합니다. byte 패키지의 알려진 이슈를 예로 들어보면.
// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.함수, 유형, 중복되거나 불필요한 전체 패키지를 만들어야 할때도 있지만 이제까지 만든 프로그램과 호환성을 유지해야 합니다. 사용하면 안된다는 신호는 다른 사람이 그 정보를 얻도록 "Deprecated"를 주석의 처음에 추가하세요. 표준 라이브러리에 그 예제가 몇가지 있습니다.
주석을 HTML로 변환할 사용하는 몇가지 규익이 있습니다.
- 이어지는 텍스트는 같은 문단으로 이해합니다. 문단을 분리하려면, 빈 줄을 남겨둬야 합니다.
- 미리 서식이 지정된 텍스트는 주변의 주석과 비교하여 들여써야 합니다. ( gob의 doc.go를 참조하세요. )
- URL은 HTML링크로 변경되며, 별도의 마크업은 필요없습니다.
어떤 규칙도 평범하지 않은 것을 하라고 하지 않습니다.
사실, godoc의 접근 방식 중 제일은 사용하기 쉽다는 것입니다. 그래서 표준라이브러리를 포함한 많은 Go 코드들이 이미 규칙을 따르고 있습니다.
당신의 코드도 위에서 설명한 주석을 사용하므로써 훌륭한 문서화를 할 수 있습니다. 설치된 어떤 Go 패키지라도, 어떤 워크스페이스에서도 godoc을 접근할 수 있으며, 경로를 추가하거나 소스코드 디렉토리를 명기함으로써 사용할 수 있습니다.
이제부터는 원문에는 포함되지 않고, 제가 godoc을 사용해보고 추가한 글입니다.
윈도우에서 해보니, go만 설치해서는 안되고 별도로 godoc을 설치해 줘야 합니다.
> go get -v golang.org/x/tools/cmd/godoc
그리고, godoc은 CLI에서는 동작하지않고, web 인터페이스만 동작합니다. CLI에서는 'go doc'을 사용해야 합니다.
godoc을 사용해보기 위해 다음 소스코드를 문서화 했습니다. "src/main/string.go"
// Package string This algorithm:search the given pattern in the given text.
// If pattern is found from index position i in the text,
// it is added to positions.
// Time Complexity : O(n*m)
// n = length of text
// m = length of pattern
package string
import (
"fmt"
)
func naivePatternSearch(text string, pattern string) []int {
var positions []int
for i := 0; i < len(text)-len(pattern); i++ {
var match bool = true
for j := 0; j < len(pattern); j++ {
if text[i+j] != pattern[j] {
match = false
break
}
}
if match {
positions = append(positions, i)
}
}
return positions
}
func main() {
text := "ABAAABCDBBABCDDEBCABC"
pattern := "ABC"
var positions []int = naivePatternSearch(text, pattern)
if len(positions) == 0 {
fmt.Printf("Pattern not found in given text!")
} else {
fmt.Printf("Pattern found in following position:\n")
fmt.Printf("%v", positions)
}
}> godoc -http=localhost:6060
어떤식으로 문서화가 되는지 짐작은 할 수 있을 것 같습니다. 그리고 CLI에서 문서화는
> go doc .
문서화를 해 주지만, 파일을 생성해주지는 않고, 파일을 생성하려면 다른 트릭이 필요한 것 같습니다.