새로운 go1.19 문서 주석으로 전환된 대형 저장소

go 1.19에는 링크와 목록을 쉽게 삽입할 수 있는 새로운 문서 주석 서식 기능이 도입되었습니다.

자세한 내용은 여기에서 설명합니다 → https://go.dev/doc/comment

링크 및 목록

링크는 이전에 필요했던 전체 URL을 삽입하지 않고 사용자에게 힌트를 제공하여 문서를 향상시킬 수 있기 때문에 아마도 가장 흥미로운 기능일 것입니다.

// The allowed shortcut operators follow:
//   - [Empty]    → $^Empty
//   - [Ignore]   → $^Ignore
//   - [NaN]      → $^NaN
//   - [Nil]      → $^Nil
//   - [NotEmpty] → $^NotEmpty
//   - [NotNaN]   → $^NotNaN
//   - [NotNil]   → $^NotNil
//   - [NotZero]  → $^NotZero
//   - [Zero]     → $^Zero
//
// TypeBehind method returns the [reflect.Type] of the expectedJSON
// once JSON unmarshaled. So it can be bool, string, float64, []any,
// map[string]any or any in case expectedJSON is "null".
//
// See also [JSONPointer], [SubJSONOf] and [SuperJSONOf].

생산:



목록 기능은 위에서도 사용됩니다. go 1.19 이전에는 들여쓰기된 글머리 기호가 단순 코드 블록으로 감지되어 고정폭 글꼴로 표시되었습니다.

링크는 로컬 내보낸 식별자(예: JSONPointer 또는 SubJSONOf )와 다른 패키지의 식별자(예: reflect.Type )를 참조할 수 있습니다.

다른 리소스에 대한 링크를 생성하기 위해 이제 다음과 같이 Markdown shortcut reference link format(선택적 제목 텍스트 없이)를 사용하여 링크를 정의할 수 있습니다.

// MultipartBody is a body of a multipart/form-data HTTP request (by
// default, or any other multipart/… body, see MediaType field) as
// defined in [RFC 2046] to be used as a [io.Reader] body of
// [http.Request] and so compliant with [RFC 2388]. It implements
// [io.Reader] and can only be read once. See [PostMultipartFormData]
// and [TestAPI.PostMultipartFormData] for examples of use.
//
// [RFC 2046]: https://tools.ietf.org/html/rfc2046
// [RFC 2388]: https://tools.ietf.org/html/rfc2388

생산:



이러한 바로 가기는 선언된 주석으로 범위가 지정됩니다.

전체 예

대규모 리포지토리에서 결과를 확인하기 위해 go-testdeep의 주석을 조정하여 이러한 새로운 기능을 최대한 활용했습니다.

영향을 받는 각 패키지의 결과를 볼 수 있습니다.

https://pkg.go.dev/github.com/maxatome/go-testdeep/td

https://pkg.go.dev/github.com/maxatome/go-testdeep/helpers/tdhttp

https://pkg.go.dev/github.com/maxatome/go-testdeep/helpers/tdsuite

https://pkg.go.dev/github.com/maxatome/go-testdeep/helpers/tdutil

몇 가지 언급

pkg.go.dev가 아직 목록에서 [links]를 처리하지 않은 것 같습니다. godoc의 마지막 버전이 제대로 처리하기 때문에 "아직"이라고 말합니다. 그래서 곧 해결될 것 같아요.

구조체 필드 링크는 표준 패키지에서 작동하지만 로컬/현재 패키지에서는 작동하지 않습니다. 예를 들어 [http.Cookie.Raw]는 Raw 패키지(example)에서 Cookie의 net/http 필드에 대한 링크를 생성하지만 go-testdeeptd 패키지[ContextConfig.RootName]에서는 그대로 유지되므로 다음으로 변경되지 않습니다. godoc 의 마지막 버전을 사용하는 경우에도 링크.

단일 키워드가 여러 선언을 그룹화하는 경우 링크는 var 또는 const 주석에서 처리되지 않습니다.

// DefaultContextConfig is the default configuration used to render
// tests failures. If overridden, new settings will impact all Cmp*
// functions and [*T] methods (if not specifically configured.)
var DefaultContextConfig = ContextConfig{…}

괜찮지만:

var (
  // DefaultContextConfig is the default configuration used to render
  // tests failures. If overridden, new settings will impact all Cmp*
  // functions and [*T] methods (if not specifically configured.)
  DefaultContextConfig = ContextConfig{
)

작동하지 않고[*T] 생성된 godoc에 그대로 남아 있습니다. 너무 나쁘다.

몇 가지 아이디어

[x] 는 예를 들어 https://pkg.go.dev/builtin#x 과 같이 error 를 가리키는 내장 함수일 수 있습니다. 모든 기본 유형은 서명에서 볼 수 있습니다.

아마도 패키지 문서 자체에서 패키지에 대한 바로 가기 참조 링크를 전역으로 갖는 것이 멋질 수 있습니다. 각 주석에서 동일한 바로 가기를 반복해서 선언하는 것을 피할 수 있습니다.

바로 가기 참조 링크가 간접 URL을 허용한다는 점이 흥미로울 수 있습니다. 예를 들어 td에서 나는 종종 Cmp* 함수에 대해 이야기합니다. 매번 Cmp 함수(Cmp* 시리즈의 첫 번째 함수)를 참조하고 싶습니다. 이렇게 하려면 바로 가기에 전체 URL을 설정해야 합니다.

// [Cmp*]: https://pkg.go.dev/github.com/maxatome/go-testdeep/td#Cmp

단순히 다음을 사용하는 동안:

// [Cmp*]: Cmp

pkg.go.dev가 다른 곳에서 하는 것처럼 [Cmp] 참조를 피합니다.

결론

이러한 새로운 기능을 사용한 결과는 꽤 멋집니다. 패키지 작성자가 문서를 개선하여 사용자가 보다 친숙한 방식으로 API를 쉽게 검색할 수 있기를 바랍니다.