Я разрабатываю пакет, содержащий вложенные пакеты, которые помогут организовать мой код. Мой пакет верхнего уровня предоставляет некоторые «псевдонимы» общих функций, вложенных в другие пакеты, как это делают многие другие проекты. Например: https://github.com/cloudevents/sdk-go/blob/main/v2/alias.go
Все работает отлично. Однако документы go, похоже, не привязаны к псевдониму, а имеют только исходное определение.
Вот минимальный пример:
// NEW FILE: <module_root>/models/models.go
package models
type MyType struct {
// comment
num int
// other comment
text string
}
// Repeats MyType.text MyType.num times
func (t *MyType) Repeat() string {
rStr := ""
for i := 0; i < t.num; i++ {
rStr += t.text
}
return rStr
}
// Create MyType with specified arguments
func NewMyType(num int, text string) MyType {
return MyType{
num: num,
text: text,
}
}
// NEW FILE: <module_root>/alias.go
package mymodule
import models
type MyType = models.MyType
var NewMyType = models.NewMyType
Интересно, что документ go, похоже, показывает, что MyType имеет метод Repeat(), но не показывает определение его структуры и связанные с ней комментарии, как при просмотре models.MyType. Кроме того, для NewMyType отображается только сигнатура функции, а не документация go, существующая в models.NewMyType.
Как я могу предоставить уже определенные документы go для этого псевдонима типа и var «псевдоним функции»?
Я также пытался просмотреть документацию по документации go doc и не нашел ни одной заметки об этом или способа «копировать»/«переслать» комментарий go doc.

Псевдонимы предназначены для рефакторинга кодовой базы, поэтому у вас будет документация по новому, рефакторизованному коду, а старый, потенциально устаревший код будет заменен псевдонимом.
В вашем случае mymodule будет старый модуль, используемый существующим устаревшим кодом, и models новый пакет с документацией, предназначенной для использования новым кодом.
Таким образом, никакой «пересылки» и «обратной» документации не предусмотрено — новый код должен использовать только что перемещенные пакеты.
Было бы полезно добавить дополнительную документацию, например «устарело, используйте models.MyType» к псевдониму mymodule.MyType.
Нет. Предполагаемая функциональность переносится на новый тип без предоставления документации по старым (устаревшим) API. Я предполагаю, что вы хотите предоставить «альтернативные» способы доступа к вашему API, но я не уверен, действительно ли я понимаю ваш вариант использования.
Цель состоит в том, чтобы иметь обязательную внутреннюю структуру (в идеале — перенести большую часть работы в internal) без необходимости навязывать ту же структуру конечным пользователям пакета. Им не обязательно знать, что у нас есть субпакет models и субпакет implementation. Они просто знают, что я выношу определенные функции из этих пакетов в основной модуль.
Хорошо, это может быть целью, но на самом деле это не поддерживается моделью Go. Дизайн предпочитает другую модель дизайна. Не знаю, можно ли считать это ответом на ваш вопрос, но это все, что я могу вам дать.
Я ценю ответ. Однако даже при использовании псевдонимов типов для рефакторинга (или для других «менее подходящих» целей) я все равно хочу предоставить документацию по типу, на который указывает псевдоним. То же самое и с переменной, которая действует как «псевдоним» другой функции. Существует ли в этом случае соглашение о совместном использовании комментариев go doc?