Documentation of an exported function should start with the function’s name GO-D5001
Documentation
Minor
6 months ago
—
8 months old
comment on exported function NewConcurrentMiddleware should be of the form "NewConcurrentMiddleware ..."
58 }
59}
60
61// NewConcurrentMiddlewareWithLogger creates a proxy middleware that enables sending several requests concurrently.62// Is recommended to use the version with a logger param.
63func NewConcurrentMiddleware(remote *config.Backend) Middleware {
64 return NewConcurrentMiddlewareWithLogger(logging.NoOp, remote)comment on exported function EmptyMiddlewareWithLogger should be of the form "EmptyMiddlewareWithLogger ..."
81// response, err := p(ctx, r)
82type Middleware func(next ...Proxy) Proxy
83
84// EmptyMiddlewareWithLoggger is a dummy middleware, useful for testing and fallback 85func EmptyMiddlewareWithLogger(logger logging.Logger, next ...Proxy) Proxy {
86 if len(next) > 1 {
87 logger.Fatal("too many proxies for this proxy middleware: EmptyMiddleware only accepts 1 proxy, got %d", len(next))
Description
Doc comments work best as complete sentences, which allow a wide variety of automated presentations. The first sentence should be a one-sentence summary that starts with the name being declared.
If every doc comment begins with the name of the item it describes, you can use the doc subcommand of the go tool and run the output through grep.
See https://golang.org/doc/effective_go.html#commentary for more information on how to write good documentation.
Bad practice
package main
// This function tries to summon a cybernetically enhanced duck
func SummonDucks() {
}
Recommended
package main
// SummonDucks tries to summon a cybernetically enhanced duck
func SummonDucks() {
}