В go 1.19 появились новые возможности форматирования комментариев к документам, позволяющие легко вставлять ссылки и списки.
Подробности описаны здесь → https://go.dev/doc/comment
Ссылки и списки
Ссылки, вероятно, самая интересная возможность, поскольку они позволяют улучшить документацию, предоставляя пользователям подсказки без вставки полного URL, как это было раньше:
// The allowed shortcut operators follow:
// - [Empty] → $^Empty
// - [Ignore] → $^Ignore
// - [NaN] → $^NaN
// - [Nil] → $^Nil
// - [NotEmpty] → $^NotEmpty
// - [NotNaN] → $^NotNaN
// - [NotNil] → $^NotNil
// - [NotZero] → $^NotZero
// - [Zero] → $^Zero
//
// TypeBehind method returns the [reflect.Type] of the expectedJSON
// once JSON unmarshaled. So it can be bool, string, float64, []any,
// map[string]any or any in case expectedJSON is "null".
//
// See also [JSONPointer], [SubJSONOf] and [SuperJSONOf].
производит:
Функция листинга также используется выше. До версии go 1.19 отступы определялись как простой блок кода и отображались моноширинным шрифтом.
Ссылки могут ссылаться на локальные экспортируемые идентификаторы (например, JSONPointer или SubJSONOf), а также на идентификаторы в других пакетах (например, reflect.Type).
Для создания ссылок на другие ресурсы теперь можно задавать ссылки, используя формат ссылки в формате Markdown (без необязательного текста заголовка), как показано ниже:
// MultipartBody is a body of a multipart/form-data HTTP request (by
// default, or any other multipart/… body, see MediaType field) as
// defined in [RFC 2046] to be used as a [io.Reader] body of
// [http.Request] and so compliant with [RFC 2388]. It implements
// [io.Reader] and can only be read once. See [PostMultipartFormData]
// and [TestAPI.PostMultipartFormData] for examples of use.
//
// [RFC 2046]: https://tools.ietf.org/html/rfc2046
// [RFC 2388]: https://tools.ietf.org/html/rfc2388
произвести:
Обратите внимание, что эти ярлыки привязаны к комментарию, в котором они объявлены.
Полный пример
Чтобы увидеть результат на большом репозитории, я адаптировал комментарии go-testdeep, чтобы полностью использовать преимущества этих новых возможностей.
Вы можете увидеть результат для каждого пакета, подвергшегося воздействию:
- https://pkg.go.dev/github.com/maxatome/go-testdeep/td
- https://pkg.go.dev/github.com/maxatome/go-testdeep/helpers/tdhttp
- https://pkg.go.dev/github.com/maxatome/go-testdeep/helpers/tdsuite
- https://pkg.go.dev/github.com/maxatome/go-testdeep/helpers/tdutil
Несколько замечаний
Похоже, что pkg.go.dev ещё не обрабатывает [ссылки] в списках. Я говорю «пока», потому что последняя версия godoc обрабатывает их правильно. Так что я полагаю, что скоро это будет исправлено.
Ссылки на структурные поля работают для стандартных пакетов, но не для локальных/текущих. Например, [http.Cookie.Raw] создает ссылку на поле Raw поля Cookie в пакете net/http (пример), но в пакете go-testdeep td [ContextConfig.RootName] остается нетронутым и поэтому не меняется на ссылку, даже при использовании последней версии godoc.
Ссылки не обрабатываются в комментариях var или const, когда одно ключевое слово группирует несколько объявлений:
// DefaultContextConfig is the default configuration used to render
// tests failures. If overridden, new settings will impact all Cmp*
// functions and [*T] methods (if not specifically configured.)
var DefaultContextConfig = ContextConfig{…}
это нормально, но:
var (
// DefaultContextConfig is the default configuration used to render
// tests failures. If overridden, new settings will impact all Cmp*
// functions and [*T] methods (if not specifically configured.)
DefaultContextConfig = ContextConfig{
)
не работает, [*T] остается нетронутым в сгенерированном godoc. Это очень плохо.
Некоторые идеи
[x] может быть встроенным указателем на https://pkg.go.dev/builtin#x, как error, например, для всех нативных типов, как мы видим их в сигнатурах.
Было бы здорово иметь ссылки на ярлыки, глобальные для пакета, возможно, в самой документации пакета. Это позволило бы избежать объявления в каждом комментарии одного и того же ярлыка снова и снова.
Может быть интересно, чтобы ссылки на ярлыки принимали непрямые URL. Например, в td я часто говорю о функциях Cmp*. Каждый раз я хотел бы ссылаться на функцию Cmp (первую из серии Cmp*). Чтобы сделать это, я должен задать полный URL в ярлыке:
// [Cmp*]: https://pkg.go.dev/github.com/maxatome/go-testdeep/td#Cmp
при простом использовании:
// [Cmp*]: Cmp
позволит избежать ссылки на pkg.go.dev, как это делает [Cmp] в других местах.
Заключение
Результат использования этих новых возможностей довольно крут. Будем надеяться, что авторы пакетов улучшат свою документацию, чтобы помочь своим пользователям легко обнаружить их API более дружественным способом.