what are the uses of semantic comments in Go?

Question

By analogy with this question about tags I note that there are several uses of comments in go beyond pure commentary.

Examples:

• go:generate can be used for code generation.
• godoc uses the function name to indicate comments it should interpret
• build constraints

Are there any others I've missed?

Is there a definitive list somewhere?

Some third party packages like gocontracts and go-swagger use them as well. How can they avoid conflicting with each other?

Answer 1

As noted comments are directives in go not just comments.

There is at the time of writing no definitive list. This as logged as an golang issue 28532.

Therefore I propose using this answer to make one.

Uses in the go core language and tools themselves:

• go:generate can be used for code generation.
• godoc uses the function name to indicate comments it should interpret
• Examples - document the expected output of a test (thanks @Butuzov)
• build constraints (starting with '// +build')
• Import comments e.g. 'package math // import "path"'

Notable uses in third party packages

• gocontracts - specify preconditions as comments
• go-swagger - document a ReST API using swagger
• golangci e.g. //nolint[:linter1,linter2,...]

How can they avoid conflicting with each other?

If you are developing a tool that really needs to treat comments as attributes and wish to avoid conflict with other similar uses prefix your comments with a namespace like "{mytool}: "

There are some conscious attempts at namespacing. Magic comments built into go use the "go: " prefix as in "go:generate" (except where they don't)

go-swagger uses "swagger: "

However you still need to approach this with caution and check the list here or any other source you can find.

Also consider whether comments are the best or only approach rather than using functions instead. Compare for instance (gocontracts):

// SomeFunc ensures:
//  * !strings.HasSuffix(result, "smth")
func SomeFunc(x int) (result string) {
    // ...
}

with (godbc)

func SomeFunc(x int) (result string) {
    godbc.Require(strings.HasSuffix(result,"smth");
}

Answer 2

Examples - Allow to test function for example output.

Copy/Paste from link above.

package stringutil_test

import (
    "fmt"

    "github.com/golang/example/stringutil"
)

func ExampleReverse() {
    fmt.Println(stringutil.Reverse("hello"))
    // Output: olleh
}