Большое репо перешло на новые комментарии в go1.19

В 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 более дружественным способом.

Оцените статью
devanswers.ru
Добавить комментарий