Получите документ go, чтобы следовать псевдониму типа и функциональной переменной

Я разрабатываю пакет, содержащий вложенные пакеты, которые помогут организовать мой код. Мой пакет верхнего уровня предоставляет некоторые «псевдонимы» общих функций, вложенных в другие пакеты, как это делают многие другие проекты. Например: 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.

Создание API ввода вопросов на разных языках программирования (Python, PHP, Go и Node.js)
Создание API ввода вопросов на разных языках программирования (Python, PHP, Go и Node.js)
API ввода вопросов - это полезный инструмент для интеграции моделей машинного обучения, таких как ChatGPT, в приложения, требующие обработки...
0
0
55
1
Перейти к ответу Данный вопрос помечен как решенный

Ответы 1

Ответ принят как подходящий

Псевдонимы предназначены для рефакторинга кодовой базы, поэтому у вас будет документация по новому, рефакторизованному коду, а старый, потенциально устаревший код будет заменен псевдонимом.

В вашем случае mymodule будет старый модуль, используемый существующим устаревшим кодом, и models новый пакет с документацией, предназначенной для использования новым кодом.

Таким образом, никакой «пересылки» и «обратной» документации не предусмотрено — новый код должен использовать только что перемещенные пакеты.

Было бы полезно добавить дополнительную документацию, например «устарело, используйте models.MyType» к псевдониму mymodule.MyType.

Я ценю ответ. Однако даже при использовании псевдонимов типов для рефакторинга (или для других «менее подходящих» целей) я все равно хочу предоставить документацию по типу, на который указывает псевдоним. То же самое и с переменной, которая действует как «псевдоним» другой функции. Существует ли в этом случае соглашение о совместном использовании комментариев go doc?

Jaxton Winder 21.07.2024 21:44

Нет. Предполагаемая функциональность переносится на новый тип без предоставления документации по старым (устаревшим) API. Я предполагаю, что вы хотите предоставить «альтернативные» способы доступа к вашему API, но я не уверен, действительно ли я понимаю ваш вариант использования.

eik 22.07.2024 00:57

Цель состоит в том, чтобы иметь обязательную внутреннюю структуру (в идеале — перенести большую часть работы в internal) без необходимости навязывать ту же структуру конечным пользователям пакета. Им не обязательно знать, что у нас есть субпакет models и субпакет implementation. Они просто знают, что я выношу определенные функции из этих пакетов в основной модуль.

Jaxton Winder 22.07.2024 20:43

Хорошо, это может быть целью, но на самом деле это не поддерживается моделью Go. Дизайн предпочитает другую модель дизайна. Не знаю, можно ли считать это ответом на ваш вопрос, но это все, что я могу вам дать.

eik 22.07.2024 20:47

Другие вопросы по теме