Sdílet prostřednictvím

Komentáře

  • Článek

Komentáře začínají dvěma lomítky (//) a pokračujte až do konce řádku. Tyto koncové komentáře se můžou objevit kdekoli ve zdrojovém kódu. Q# v současné době nepodporuje blokové komentáře.

Komentáře dokumentace

Komentáře, které začínají třemi lomítky, ///jsou zpracovávány speciálně kompilátorem, když se objeví před typem nebo volatelnou deklaraci. V takovém případě se jejich obsah považuje za dokumentaci k definovanému typu nebo volání, jako u jiných jazyků .NET.

V /// komentářích je text, který se má zobrazit jako součást dokumentace k rozhraní API, formátovaný jako Markdown s různými částmi dokumentace označenými speciálně pojmenovanými záhlavími. Jako rozšíření Markdownu je možné zahrnout křížové odkazy na operace, funkce a uživatelem definované typy Q# pomocí @"<ref target>," místa, kde <ref target> je nahrazen plně kvalifikovaným názvem objektu kódu, na který se odkazuje. Volitelně může modul dokumentace také podporovat další rozšíření Markdownu.

Příklad:

/// # 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# rozpozná následující názvy jako hlavičky komentářů dokumentace.

  • Shrnutí: Krátký souhrn chování funkce nebo operace nebo účelu typu. První odstavec souhrnu se používá k najetí myší. Měl by to být prostý text.
  • Popis: Popis chování funkce nebo operace nebo účel typu. Souhrn a popis jsou zřetězeny tak, aby vytvořily vygenerovaný soubor dokumentace pro funkci, operaci nebo typ. Popis může obsahovat vložené symboly a rovnice ve formátu LaTeX.
  • Vstup: Popis vstupní řazené kolekce členů pro operaci nebo funkci. Může obsahovat další pododdíly Markdownu označující každý prvek vstupní řazené kolekce členů.
  • Výstup: Popis řazené kolekce členů vrácené operací nebo funkcí
  • Parametry typu: Prázdný oddíl, který obsahuje jeden další pododdíl pro každý parametr obecného typu.
  • Pojmenované položky: Popis pojmenovaných položek v uživatelem definovaném typu. Může obsahovat další pododdíly Markdownu s popisem pro každou pojmenovanou položku.
  • Příklad: Krátký příklad operace, funkce nebo typu, které se používají.
  • Poznámky: Různé prose popisující určitý aspekt operace, funkce nebo typu.
  • Viz také: Seznam plně kvalifikovaných názvů označujících související funkce, operace nebo uživatelem definované typy.
  • Odkazy: Seznam odkazů a citací pro dokumentovanou položku.