Каковы смысловые смысловые комментарии в Go?

Question

По аналогии с этот вопрос о тегах. Я отмечаю, что есть несколько вариантов использования комментариев, выходящих за рамки чистого комментария.

Примеры:

• go: generate может использоваться для генерации кода.
• godoc использует имя функции для обозначения комментариев, которые следует интерпретировать
• build ограничения

Есть ли другие, которые я пропустил?

Есть ли где-нибудь определенный список?

Некоторые сторонние пакеты, такие как gocontracts и go-swagger , также используют их.Как они могут избежать конфликта друг с другом?

Answer 1

Как уже отмечалось комментарии - это директивы в go , а не просто комментарии.

На момент написания этой статьи нет определенного списка.Это записано как выпуск golang 28532 .

. Поэтому я предлагаю использовать этот ответ, чтобы сделать его.

Использует основной язык go и сами инструменты:

• go: generate может использоваться для генерации кода.
• godoc использует имя функции для обозначения комментариев, которые следует интерпретировать
• Примеры - документировать ожидаемый результат теста (спасибо @Butuzov)
• build ограничения (начиная с ' // + build ')
• Импортировать комментарии например, ' пакетная математика // import "путь" '

Известное использование в сторонних пакетах

• gocontracts - указать предварительные условия в качестве комментариев
• go-swagger - документировать API ReST, используя сваггер
• golangci например, //nolint[:linter1,linter2,...]

Как они могут избежать конфликтов друг с другом?

Если вы разрабатываете инструмент, который реальноLy должен рассматривать комментарии как атрибуты и избегать конфликтов с другими подобными видами использования. Перед комментариями ставьте перед пространством имен, например, " {mytool} :"

Существуют некоторые сознательные попытки пространства имен.Магические комментарии, встроенные в go, используют префикс «go:», как в «go: generate» (кроме случаев, когда они этого не делают)

go-swagger использует «swagger:»

Однако вы по-прежнемунужно подходить к этому с осторожностью и проверить список здесь или любой другой источник, который вы можете найти.

Также подумайте, являются ли комментарии лучшим подходом или только вместо использования функций вместо этого.Сравните, например, ( gocontracts ):

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

с ( godbc )

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

Answer 2

Примеры - Разрешить тестирование функции для вывода example.

Копирование / вставка по ссылке выше.

package stringutil_test

import (
    "fmt"

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

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