共用方式為

註解

  • 發行項

註解是以兩個正斜線 (//) 為開頭，然後繼續直到行尾為止。 這類行結尾註解可能會顯示在原始程式碼中的任何位置。 Q# 目前不支援區塊註解。

文件註解

以三個正斜線 (///) 為開頭的註解會在編譯器於類型或可呼叫檔宣告之前出現時，由編譯器進行特殊處理。 在此情況下，會將其內容視為已定義類型或可呼叫檔的文件，就像其他 .NET 語言一樣。

在 /// 註解中，顯示為 API 文件一部分的文字會格式化為 Markdown，並以特殊命名的標頭指出文件的不同部分。 在 Q# 中，您可以使用 @"<ref target>," 包含作業、函式和使用者定義型別的交互參考，做為 Markdown 的延伸模組，其中 <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 子區段，以及每個已命名項目的描述。
  • 範例：使用中的作業、函式或類型的簡短範例。
  • 備註：描述作業、函式或類型某些層面的其他 prose。
  • 另請參閱：指出相關函式、作業或使用者定義型別的完整名稱清單。
  • 參考：已記載項目的參考與引文清單。