Поделиться через

Комментарии

  • Статья

В начале текста комментариев ставятся две косые черты (//). Текст продолжается до конца строки. Такие комментарии могут появляться в любом участке исходного кода. Сейчас Q# не поддерживает блочные комментарии.

Комментарии для документации

Комментарии, текст которых начинается с трех косых черт, ///, обрабатываются компилятором особым образом, если они появляются перед объявлением типа или вызываемого элемента. В этом случае их содержимое расценивается как документация для определенного типа или вызываемого объекта, как и для других языков .NET.

Внутри комментариев /// текст, который будет отображаться как часть документации по API, форматируется как Markdown, а различные части документации определяются специально именованными заголовками. Перекрестные ссылки на операции, функции и пользовательские типы в Q# как расширение Markdown можно включать с помощью @"<ref target>,", где <ref target> заменяется полным именем объекта кода, на который указывает ссылка. Кроме того, при необходимости обработчик документации может поддерживать дополнительные расширения Markdown.

Например:

/// # Summary
/// Given an operation and a target for that operation,
/// applies the given operation twice.
///
/// # Input
/// ## op
/// The operation to be applied.
/// ## target
/// The target to which the operation is to be applied.
///
/// # Type Parameters
/// ## 'T
/// The type expected by the given operation as its input.
///
/// # Example
/// ```Q#
/// // Should be equivalent to the identity.
/// ApplyTwice(H, qubit);
/// ```
///
/// # See Also
/// - Microsoft.Quantum.Intrinsic.H
operation ApplyTwice<'T>(op : ('T => Unit), target : 'T) : Unit {
    op(target);
    op(target);
}

Q# распознает следующие имена как заголовки комментариев документации.

  • Сводка. Краткая сводка по поведению функции либо операции или назначению типа. Первый абзац сводки используется для сведений о наведении. Он должен быть обычным текстом.
  • Описание. Описание поведения функции либо операции или назначения типа. Сводка и описание объединяются, образуя сгенерированный файл документации для функции, операции или типа. Описание может содержать встроенные символы и уравнения в формате LaTeX.
  • Входные данные. Описание входного кортежа для операции или функции. Может содержать дополнительные подразделы Markdown, указывающие каждый элемент входного кортежа.
  • Выходные данные. Описание кортежа, возвращенного операцией или функцией.
  • Параметры типа. Пустой раздел, который содержит один дополнительный подраздел для каждого параметра универсального типа.
  • Именованные элементы. Описание именованных элементов в пользовательскому типе. Может содержать дополнительные подразделы Markdown с описанием для каждого именованного элемента.
  • Пример. Краткий пример использования операции, функции или типа.
  • Комментарии. Различные примечания, описывающие некоторые аспекты операции, функции или типа.
  • См. также. Список полных имен, определяющих связанные функции, операции или пользовательские типы.
  • Ссылки. Список ссылок для задокументированного элемента.