Documentation of an exported function should start with the function’s name GO-D5001
Documentation
Minor
3 days ago
—
a year old
comment on exported method RegistryAuth should be of the form "RegistryAuth ..."
47 return r, nil
48}
49
50// override this function to provider infrastructure-specific authentication, such as 51// token swapping for ecr
52func (p *Provider) RegistryAuth(host, username, password string) (string, string, error) {
53 return username, password, nilcomment on exported method GetNodesMetrics should be of the form "GetNodesMetrics ..."
130 return structs.Metrics{*cpum, *memm}, nil
131}
132
133// nodeNames: single or comma seperated node names134func (m *MetricScraperClient) GetNodesMetrics(nodeNames string, metricType structs.ScraperMetricType) (*structs.ScraperMetricList, error) {
135 if m.host == "" {
136 return nil, errors.WithStack(fmt.Errorf("unimplemented"))comment on exported method SetEnv should be of the form "SetEnv ..."
414 }
415}
416
417// used only for tests418func (m *Manifest) SetEnv(env map[string]string) {
419 m.env = env
420}comment on exported method SetAttributes should be of the form "SetAttributes ..."
405 return env, nil
406}
407
408// used only for tests409func (m *Manifest) SetAttributes(attrs []string) {
410 m.attributes = map[string]bool{}
411
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() {
}