Godoc документация не выводит списки - PullRequest
Новая
       16

Godoc документация не выводит списки

0 голосов
/ 10 октября 2018

На протяжении всего проекта я отвечаю за тестирование и документирование, создавал документацию для функций и методов в следующем формате: 

// CheckPermissionArray checks that values is an array that contains the `expectedValue`
//
// Parameters:
//
// - `values` : the array to check
// - `expectedValue` : the value to search for
//
// Returns:
//
// - an error iff `expectedValue` is not in `values`

Босс и другие программисты одобряют этот формат,но проблема в том, что godoc не распознает список:

enter image description here

Есть ли способ получить список, который будет распознан?

Код Visual Studio, в какой-то степени, распознавал эту документацию просто отлично, хотя и с ошибками.

1 Ответ

0 голосов
/ 10 октября 2018

Как отмечали другие, «списки» в комментариях не будут преобразованы в списки HTML (например, <ol>, <ul>).

Рекомендуемое чтение: Годок: документирование кода Go .Цитата из этого:

Годок концептуально связан с Докустрией Python и Javadoc * Java3 в Java, но его дизайн проще.Комментарии, прочитанные godoc, не являются языковыми конструкциями (как в Docstring), и при этом они не должны иметь свой собственный машиночитаемый синтаксис (как в Javadoc).Комментарии Godoc - это просто хорошие комментарии, которые вы хотели бы прочитать, даже если godoc не существовало.

При создании документов HTML выполняются только следующие преобразования:

Существует несколько правил форматирования, которые Годок использует при преобразовании комментариев в HTML:

  • Последующие строки текста считаются частью одного и того же абзаца;Вы должны оставить пустую строку для разделения абзацев.
  • Предварительно отформатированный текст должен иметь отступ относительно окружающего текста комментария (см., например, gob's doc.go ).
  • URL будут преобразованы в ссылки HTML;специальная разметка не требуется.

Что вы можете сделать, чтобы «подражать» спискам:

Используя следующий комментарий: 

// Fv1 is just an example.
//
// Here's a list:
//
// -First item
//
// -Second item
//
// -Third item
//
// This is the closing line.

В результате получается следующий вывод:

Fv1 - просто пример.

Вот список:

-Первый элемент

-Второй элемент

-Третий элемент

Это закрывающая строка.

Небольшое изменение, дающее лучший визуальный внешний вид, заключается в использовании • символа маркера вместотире: 

// Fv1 is just an example.
//
// Here's a list:
//
// • First item
//
// • Second item
//
// • Third item
//
// This is the closing line.

Результаты (github.com/google/go-cmp использует его):

Fv1 - только пример.

Вотсписок:

• Первый элемент

• Второй элемент

• Третий элемент

Это заключительная строка.

Или вы можете сделать отступ для элементов списка (достаточно 1 дополнительного пробела, но вы можете использовать больше по своему вкусу): 

// Fv2 is just another example.
//
// Here's a list:
//  -First item
//  -Second item
//  -Third item
//
// This is the closing line.

Что дает это в сгенерированном документе:

Fv2 - просто еще один пример.

Вотсписок: 

-First item
-Second item
-Third item

Это закрывающая строка.

Вы можете создавать «вложенные» списки, подобные этому, отступы сохраняются (так как это будет предварительно отформатированный блок): 

// Fv3 is just another example.
//
// Here's a list:
//   -First item
//     -First.First item
//     -First.Second item
//   -Second item
//
// This is the closing line.

Результат в документе:

Fv3 - это просто еще один пример.

Вот список: 

-First item
  -First.First item
  -First.Second item
-Second item

Thisявляется закрывающей линией.

...