Документация

Документация на веб-сайте (www.antblazor.com) автоматически генерируется на основе комментариев XML в файлах кода для библиотеки. Идея заключается в том, чтобы поддерживать синхронизацию кода и документации сайта при внесении изменений. Для этого необходимо поддерживать комментарии документации в коде, используя определённые теги и форматирование вместе с некоторыми атрибутами данных. Более подробная информация об этом приведена ниже.

Подробнее о комментариях документации XML в C# см. на веб-сайте Microsoft.

Документирование компонента

Чтобы пометить компонент для отображения страницы документации, отметьте его атрибутом Documentation, пример:

[Documentation(DocumentationCategory.Components, DocumentationType.DataDisplay, "https://fullUrl.com/to/image.jpg")]

• Первый аргумент — это категория, выбираемая из перечисления.
• Второй аргумент — тип, выбираемый из перечисления.
• Третий аргумент — изображение, используемое для страницы «Обзор».
• Существует множество необязательных свойств, которые можно установить и которые влияют на результат страницы:
  • Title — используйте пользовательский заголовок для страницы. Это также влияет на URL. По умолчанию используется имя класса компонента.
  • Columns — количество столбцов демонстраций должно быть. По умолчанию — 2.
  • Subtitle — подзаголовок для страницы документации. По умолчанию равен null.
  • OutputApi — этот параметр позволяет отключить вывод API декорированного класса. По умолчанию верно (вывод API).
    • Основное использование этого в настоящее время предназначено для страниц, которые группируют несколько компонентов (например, страница типографики, страница макета и т. д.) и не имеют собственного основного компонента. Выберите компонент, который имеет смысл украсить, и установите этот параметр.
    • Обычно используется в сочетании с тегом в комментариях XML компонента для вывода API компонентов группировки (подробности о тегах XML приведены ниже).

Поддерживаемые теги XML

Существуют определённые теги, на которые проект сборки смотрит при сборке документации веб-сайта. Существуют стандартные и пользовательские теги, которые мы ищем в комментариях документации.

• — тег summary используется для описаний в большинстве мест сайта. * Для компонента/страницы он используется в блоке в самом верху страницы (прямо под заголовком и над демонстрациями). * Для членов класса, таких как свойства, параметры, поля, методы и т.д., он используется для размещения описания рядом с именем члена в разделе API страниц.
• — тег default — это пользовательский тег, используемый для предоставления значения по умолчанию для члена разделу API сайта.
  • В приведённом выше примере «что-то» будет отображаться в столбце по умолчанию рядом с членом, на котором оно находится.
  • Использование этого настоятельно рекомендуется, даже если значение по умолчанию не задано непосредственно для самого члена, а вместо этого выполняется через логику в самом коде.
  • Это могут быть короткие утверждения, такие как «если истина, 1, иначе 0».
  • К этим значениям по умолчанию на сайте не применяется форматирование.
• — теги see и seealso используются в основном для ссылки на другие места в библиотеке и, когда это возможно, для связи с этими местами на сайте.
  • see поддерживается внутри тегов summary. При предоставлении внутри сводки будет вставлен текст стиля кода в этом месте.
  • Типы и члены поддерживаются здесь. Когда используется тип, мы попытаемся поместить ссылку на страницу типа на сайте.
  • seealso поддерживается на корневом уровне документации компонентов/страниц.
  • При предоставлении здесь документация API для члена, указанного в cref, будет добавлена в порядке к разделу API страницы документации компонента.
  • В настоящее время здесь поддерживаются только типы (например, класс, а не свойство класса).
• Some text — этот тег будет заключать текст внутри него в абзац при отображении на сайте. Этот тег поддерживается внутри тегов summary и рекомендуется для использования в основной сводке компонента.
• , и внутри них. ## Добавить раздел FAQ в документацию

Разделы FAQ можно добавить в документацию, разместив файлы Markdown в нужном месте с соблюдением правил именования.

1. Поместите файл в папку: Demos/Components/[COMPONENT_NAME].

   • Замените [COMPONENT_NAME] на имя компонента, для которого должен быть размещён раздел FAQ.

2. В папке назовите файл faq.[LANG].md.

   • Замените [LANG] на код языка, на котором написан файл. Например, en-US.
   • Эти файлы в настоящее время не переведены, поэтому необходимо предоставить перевод для каждого языка.

Разное

• [Obsolete("Краткое описание причины и того, что ещё использовать")]

  • Obsolete будет отображаться на сайте с предоставленным сообщением, а также коротким сообщением о том, что оно будет удалено в будущей версии.
  • Тег Obsolete будет отображаться рядом с описанием на сайте.

• У параметров будет отображаться тег рядом с ними на сайте, указывающий, что они являются параметром компонента.

• Игнорируемые вещи и не включённые в документацию:

  • Внедрённые сервисы (с использованием атрибута [Inject]), даже если у них есть комментарии документации.
  • Каскадные параметры (с использованием атрибута [CascadingParameter]), даже если у них есть комментарии документации.
  • Специальные члены и конструкторы, независимо от комментариев документации.
  • Методы, которые игнорируются (полный список можно увидеть в поле _methodNamesToIgnore в команде GenerateDemoJsonCommand):
    • Встроенные методы, такие как Dispose, Equals и т. д.
    • Методы жизненного цикла Blazor, такие как OnAfterRender, независимо от комментариев документации.

Языки/Переводы

Все комментарии и сообщения в документации кода должны быть на английском языке. Текст автоматически переводится с английского на китайский для создания китайской документации, где это имеет смысл.

Переведено:

• Сводные теги.
• Устаревшие сообщения.
• Заголовки в таблицах API.

Не переведено:

• Файлы Markdown (например, для разделов FAQ).
• Имена членов/классов.
• Типы данных.
• Текст по умолчанию.
• Подписи методов, любая часть.

Переопределение переводов

Могут быть случаи, когда автоматический перевод недостаточен или недействителен. В этих случаях существует возможность указать перевод для тегов <summary>, используя пользовательский атрибут в теге. В настоящее время это поддерживается только для сводных тегов. Если по какой-либо причине перевод не может быть определён, будет использоваться английский язык.

Пример ниже демонстрирует использование:

/// <summary>
/// English summary
/// </summary>
/// <summary xml:lang="zh-CN">
/// Chinese summary
/// </summary>
public string SomeProperty { get; set; }

Это свойство содержит английские и китайские сводки, предоставленные одновременно. Используя атрибут xml:lang, вы можете указать язык, для которого предназначена сводка. Если атрибут не предоставлен, предполагается английский.

Служба перевода

Документация будет переведена на китайский язык с помощью Google или Azure.

• Azure: используется служба по умолчанию.

  • Требуется предоставить ключ API, если вы хотите запустить его локально. Предоставьте этот ключ и регион для вашего ключа в файле appsettings.private.json в папке Build.CLI. Этот файл игнорируется git, поэтому он не будет зафиксирован и не раскроет ваш ключ.
  • Azure предоставляет 2 миллиона символов перевода в месяц бесплатно. Подробнее см. на сайте Microsoft.

• Google: не используется, если изменение кода не делает его используемым.

  • Доступен в качестве запасного варианта, если это необходимо.
  • Не требует ключа API.
  • Очень ограничен в количестве запросов, которые могут быть сделаны. Одна сборка документов превысит этот лимит.

Чтобы избежать чрезмерных вызовов любой из служб перевода, мы кэшируем переводы. Как это работает:

1. Запрашивается перевод.
2. Проверка известных переводов — существует? Вернуть известный перевод. Не существует? Продолжить.
3. Запрос перевода.
4. Добавление перевода в список известных переводов.
5. В конце сборки записать известные переводы на диск. Это исключит любые неиспользуемые переводы, поэтому мы очищаем удалённый текст, когда что-то меняем.