cxuu/golang-skills

go-documentation

Use when writing or reviewing documentation for Go packages, types, functions, or methods.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/cxuu/golang-skills --skill go-documentation

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Go Documentation

Resource Routing

  • scripts/check-docs.sh - Run when checking exported functions, types, methods, constants, and packages for missing doc comments.
  • scripts/check-docs-ast.go - Implementation helper invoked by check-docs.sh; patch this when changing documentation analysis behavior.
  • assets/doc-template.go - Use when starting a documented package or exported API.
  • references/CONVENTIONS.md - Read when documenting parameters, context behavior, concurrency safety, cleanup, errors, or named results.
  • references/EXAMPLES.md - Read when adding runnable examples or package examples.
  • references/FORMATTING.md - Read when formatting Godoc lists, paragraphs, links, and code blocks.

Doc Comments

Normative: All top-level exported names must have doc comments.

Basic Rules

  1. Begin with the name of the object being described
  2. An article ("a", "an", "the") may precede the name
  3. Use full sentences (capitalized, punctuated)
go
// A Request represents a request to run a command.
type Request struct { ...

// Encode writes the JSON encoding of req to w.
func Encode(w io.Writer, req *Request) { ...

Unexported types/functions with unobvious behavior should also have doc comments.

Validation: After adding doc comments, run bash scripts/check-docs.sh to verify no exported symbols are missing documentation. Fix any gaps before proceeding.

Comment Sentences

Normative: Documentation comments must be complete sentences.
  • Capitalize the first word, end with punctuation
  • Exception: may begin with uncapitalized identifier if clear
  • End-of-line comments for struct fields can be phrases

Comment Line Length

Advisory: Aim for ~80 columns, but no hard limit.

Break based on punctuation. Don't split long URLs.


Struct Documentation

Group fields with section comments. Mark optional fields with defaults:

go
type Options struct {
    // General setup:
    Name  string
    Group *FooGroup

    // Customization:
    LargeGroupThreshold int // optional; default: 10
}

Package Comments

Normative: Every package must have exactly one package comment.
go
// Package math provides basic constants and mathematical functions.
package math
  • For main packages, use the binary name: // The seed_generator command ...
  • For long package comments, use a doc.go file

What to Document

Advisory: Document non-obvious behavior, not obvious behavior.
TopicDocument when...Skip when...
ParametersNon-obvious behavior, edge casesRestates the type signature
ContextsBehavior differs from standard cancellationStandard ctx.Err() return
ConcurrencyAmbiguous thread safety (e.g., read that mutates)Read-only is safe, mutation is unsafe
CleanupAlways document resource release—
ErrorsSentinel values, error types (use *PathError)—
Named resultsMultiple params of same type, action-oriented namesType alone is clear enough

Key principles:

  • Context cancellation returning ctx.Err() is implied — don't restate it
  • Read-only ops are assumed thread-safe; mutations assumed unsafe — don't restate
  • Always document cleanup requirements (e.g., Call Stop to release resources)
  • Use pointer in error type docs (*PathError) for correct errors.Is/errors.As
  • Don't name results just to enable naked returns — clarity > brevity

Runnable Examples

Advisory: Provide runnable examples in test files (*_test.go).
go
func ExampleConfig_WriteTo() {
    cfg := &Config{Name: "example"}
    cfg.WriteTo(os.Stdout)
    // Output:
    // {"name": "example"}
}

Examples appear in Godoc attached to the documented element.


Quick Reference

TopicKey Rule
Doc commentsStart with name, use full sentences
Line length~80 chars, prioritize readability
Package commentsOne per package, above package clause
ParametersDocument non-obvious behavior only
ContextsDocument exceptions to implied behavior
ConcurrencyDocument ambiguous thread safety
CleanupAlways document resource release
ErrorsDocument sentinels and types (note pointer)
ExamplesUse runnable examples in test files
FormattingBlank lines for paragraphs, indent for code

Related Skills

  • Naming conventions: See go-naming when choosing names for the identifiers your doc comments describe
  • Testing examples: See go-testing when writing runnable Example test functions that appear in godoc
  • Linting enforcement: See go-linting when using revive or other linters to enforce doc comment presence
  • Style principles: See go-style-core when balancing documentation verbosity against clarity and concision
같은 저장소의 Skills

더 많은 Skills

모든 Skills
cxuu
커뮤니티

go-code-review

Use when reviewing Go code or checking code against community style standards. Also use proactively before submitting a Go PR or when reviewing any Go code changes, even if the user doesn't explicitly request a style review. Does not cover language-specific syntax — delegates to specialized skills.

1시간 설치 수
2
GitHub Stars
189
업데이트
6월 20일
cxuu
커뮤니티

go-concurrency

Use when writing concurrent Go code — goroutines, channels, mutexes, or thread-safety guarantees. Also use when parallelizing work, fixing data races, or protecting shared state, even if the user doesn't explicitly mention concurrency primitives. Does not cover context.Context patterns (see go-context).

1시간 설치 수
2
GitHub Stars
189
업데이트
6월 20일
cxuu
커뮤니티

go-context

Use when working with context.Context in Go — placement in signatures, propagating cancellation and deadlines, and storing values in context vs parameters. Also use when cancelling long-running operations, setting timeouts, or passing request-scoped data, even if they don't mention context.Context directly. Does not cover goroutine lifecycle or sync primitives (see go-concurrency).

1시간 설치 수
2
GitHub Stars
189
업데이트
6월 20일
cxuu
커뮤니티

go-control-flow

Use when writing conditionals, loops, or switch statements in Go — including if with initialization, early returns, for loop forms, range, switch, type switches, and blank identifier patterns. Also use when writing a simple if/else or for loop, even if the user doesn't mention guard clauses or variable scoping. Does not cover error flow patterns (see go-error-handling).

1시간 설치 수
2
GitHub Stars
189
업데이트
6월 20일