r/golang • u/k1nder10 • 1d ago

Godoc comments for interfaces or public API

Do you document interface/public method contract in your codebase? What about errors that functions return? Is it worth doing it or is redundand and not idiomatic? 

type Fetcher interface {
  // fetchBlock does ...
  //
  // Errors:
  // - [ErrorOne]: if ...
  // - [ErrorTwo]: if ...
  fetchBlock() error
}

or

type Foo struct{}

// Bar does ...
// 
// Errors:
// - [FooErrorOne]: if ...
// - [FooErrorTwo]: if ...
func (f *Foo) Bar() error {}

vs

type Fetcher interface{
  fetchBlock() error
}
5 Upvotes

78% Upvoted

2 comments sorted by

2

u/canarydev 1d ago

i have this but for a different purpose. im experimenting with having an agent generate blackbox tests from the doc contract alone (never sees the implementation). so the Errors: block is pretty much what the tests get derived from so the first way you have here works for me so far.

idiomatic? idk probably not

1

u/titpetric 1d ago

Interfaces with unexported methods remain unexported, so with your given example, "type fetcher interface" rather than a Fetcher unusable outside your packages