通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

注释

  • 项目

注释以两个正斜杠 (//) 开头，一直持续到行尾。 这种行尾注释可以出现在源代码中的任何位置。 Q# 目前不支持块注释。

文档注释

以三个正斜杠 /// 开头的注释出现在类型或可调用对象声明之前时，编译器会对其进行特殊处理。 在这种情况下，与在其他 .NET 语言中一样，这些注释的内容被视为定义的类型或可调用对象的文档说明。

在 /// 注释中，作为 API 文档的一部分出现的文本设置为 Markdown 格式，文档的不同部分由特殊命名的标头指示。 作为 Markdown 的扩展，可以使用 @"<ref target>," 来包含对 Q# 中运算、函数和用户定义的类型的交叉引用，其中 <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 子节，其中包含每个命名项的说明。
  • 示例：使用的运算、函数或类型的简短示例。
  • 备注：描述运算、函数或类型的某些方面的杂项陈述。
  • 另请参阅：指示相关函数、运算或用户定义类型的完全限定名称的列表。
  • 参考：所述项的参考文章和引述段落的列表。