次の方法で共有

コメント

  • [アーティクル]

コメントは 2 つのスラッシュ (//) で始まり、行の終わりまで続きます。 このような行末のコメントは、ソースコード内の任意の場所に記述できます。 Q# では、ブロック コメントは現在サポートされていません。

ドキュメント コメント

3つのスラッシュ /// で始まるコメントは、型または callable の宣言の前に出現すると、コンパイラによって特別な処理が行われます。 その場合、その内容は、他の .NET 言語と同様に、定義された型または callable のドキュメントとして取得されます。

/// コメント内では、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# では、次の名前がドキュメントのコメント ヘッダーとして認識されます。

  • Summary: 関数または操作の動作、または型の目的の簡単な概要。 概要の最初の段落は、ホバー情報に使用されます。 これはプレーン テキストである必要があります。
  • Description: 関数または操作の動作、または型の目的を説明します。 概要と説明を連結して、関数、操作、または型の生成されたドキュメント ファイルが作成されます。 説明には、インラインの LaTeX 形式の記号と式を含めることができます。
  • Input: 操作または関数の入力タプルの説明。 入力タプルの各要素を示す追加の Markdown サブセクションを含めることができます。
  • Output: 操作または関数によって返されるタプルの説明。
  • Type Parameters: ジェネリック型パラメーターごとに 1 つの追加のサブセクションを含む空のセクション。
  • Named Items: ユーザー定義型の名前付き項目の説明。 名前付き項目ごとの説明を含む追加の Markdown サブセクションを含めることができます。
  • Example: 使用されている操作、関数、または型の短い例。
  • Remarks: 操作、関数、または型のいくつかの側面を説明するその他の PROSE。
  • See Also: 関連する関数、操作、またはユーザー定義型を示す完全修飾名の一覧。
  • References: 文書化された項目の参照および引用の一覧。