golint-sl

Appearance

exporteddoc

About 369 words

Ensures exported symbols have documentation.

Category

Architecture

What It Checks

This analyzer detects exported functions, types, variables and constants without documentation comments. Methods, test files and Err-prefixed sentinel errors are not checked.

The doc comment of a function, a type, or a standalone var or const declaring one name must start with that name. Line comments (//) and block comments (/* */) both count; directives such as //go:generate or //nolint:... don't. In a parenthesized var or const group, a doc comment on the group or on the spec is enough, since a comment there often heads a section of the group.

Why It Matters

Documentation is essential for:

  • API usability
  • IDE support (hover documentation)
  • Generated documentation (godoc)
  • Maintainability

Examples

Bad: No Documentation

package user

type Service struct {  // Missing doc
    db *sql.DB
}

func New(db *sql.DB) *Service {  // Missing doc
    return &Service{db: db}
}

func (s *Service) Get(id string) (*User, error) {  // Missing doc
    // ...
}

Good: With Documentation

package user

// Service provides user management operations.
type Service struct {
    db *sql.DB
}

// New creates a new user Service with the given database connection.
func New(db *sql.DB) *Service {
    return &Service{db: db}
}

// Get retrieves a user by their unique identifier.
// Returns ErrNotFound if the user doesn't exist.
func (s *Service) Get(id string) (*User, error) {
    // ...
}

Documentation Format

// FunctionName does something specific.
//
// It handles edge cases like X and Y.
// Returns an error if Z fails.
func FunctionName(param Type) (Result, error)

// TypeName represents a thing.
//
// Use NewTypeName to create instances.
type TypeName struct {
    // Field1 is the primary identifier.
    Field1 string

    // Field2 controls behavior X.
    Field2 int
}

// ConstantName is the maximum allowed value for X.
const ConstantName = 100

// ErrNotFound is returned when the requested resource doesn't exist.
var ErrNotFound = errors.New("not found")

Configuration

# .golint-sl.yaml
analyzers:
  exporteddoc: true  # enabled by default

When to Disable

  • Internal packages
  • Protobuf-generated code
  • Early prototyping
analyzers:
  exporteddoc: false

See Also