Комментарии

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

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

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

В /// примечания текст, который будет отображаться в документации по API, форматируется как Markdownс различными частями документации, указанной специально именованными заголовками. Как расширение Markdown, перекрестные ссылки на операции, функции и типы структур в Q# можно включить с помощью @"<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 с описанием для каждого именованного элемента.
• пример: краткий пример операции, функции или типа.
• Примечания: прочие прозе, описывающие некоторые аспекты операции, функции или типа.
• см. также: список полных имен, указывающих на связанные функции, операции или типы структур.
• ссылки: список ссылок и ссылок для документированного элемента.