Kommentare

Kommentare beginnen mit zwei Schrägstrichen (//) und werden bis zum Ende der Zeile fortgesetzt. Solche Zeilenendekommentare können überall im Quellcode vorkommen. Q# unterstützt derzeit keine Blockkommentare.

Dokumentationskommentare

Kommentare, die mit drei Schrägstrichen (///) beginnen, werden vom Compiler besonders behandelt, wenn sie vor einem Typ oder einer aufrufbaren Deklaration stehen. In diesem Fall wird ihr Inhalt wie bei anderen .NET-Sprachen als Dokumentation für den definierten Typ oder das aufrufbare Element betrachtet.

Innerhalb von ///-Kommentaren wird der Text, der als Teil der API-Dokumentation angezeigt werden soll, als Markdown formatiert, wobei verschiedene Teile der Dokumentation durch speziell benannte Header gekennzeichnet werden. Als Erweiterung von Markdown können Querverweise auf Vorgänge, Funktionen und benutzerdefinierte Typen in Q# mit @"<ref target>," eingefügt werden, wobei <ref target> durch den voll qualifizierten Namen des Codeobjekts ersetzt wird, auf das verwiesen wird. Optional kann eine Dokumentationsengine auch zusätzliche Markdownerweiterungen unterstützen.

Beispiel:

/// # 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# erkennt die folgenden Namen als Header für Dokumentationskommentare.

• Zusammenfassung: Eine kurze Zusammenfassung des Verhaltens einer Funktion oder eines Vorgangs oder des Zwecks eines Typs. Der erste Absatz der Zusammenfassung wird für QuickInfos verwendet. Dabei muss es sich um Nur-Text handeln.
• Beschreibung: Eine Beschreibung des Verhaltens einer Funktion oder eines Vorgangs oder des Zwecks eines Typs. Zusammenfassung und Beschreibung werden verkettet, um die generierte Dokumentationsdatei für die Funktion, den Vorgang oder den Typ zu bilden. Die Beschreibung kann Inline-Symbole und -Gleichungen im LaTeX-Format enthalten.
• Eingabe: Eine Beschreibung des Eingabetupels für einen Vorgang oder eine Funktion. Kann zusätzliche Markdown-Unterabschnitte enthalten, welche die einzelnen Elemente des Eingabetupels angeben.
• Ausgabe: Eine Beschreibung des Tupels, das von einem Vorgang oder einer Funktion zurückgegeben wird.
• Typparameter: Ein leerer Abschnitt, der einen zusätzlichen Unterabschnitt für jeden generischen Typparameter enthält.
• Benannte Elemente: Eine Beschreibung der benannten Elemente in einem benutzerdefinierten Typ. Kann zusätzliche Markdown-Unterabschnitte mit der Beschreibung für jedes benannte Element enthalten.
• Beispiel: Ein kurzes Beispiel für den Vorgang, die Funktion oder den Typ, der verwendet wird.
• Hinweise: Verschiedene Texte, die einen Aspekt des Vorgangs, der Funktion oder des Typs beschreiben.
• Siehe auch: Eine Liste vollqualifizierter Namen, die verwandte Funktionen, Vorgänge oder benutzerdefinierte Typen angeben.
• Verweise: Eine Liste von Verweisen und Zitaten für das dokumentierte Element.