Udostępnij za pośrednictwem

Komentarze

  • Artykuł

Komentarze zaczynają się od dwóch ukośników (//) i kontynuują do końca wiersza. Takie komentarze końcowe mogą pojawiać się w dowolnym miejscu w kodzie źródłowym. Q# obecnie nie obsługuje komentarzy blokowych.

Komentarze dokumentacji

Komentarze, które zaczynają się od trzech ukośników do przodu, ///, są traktowane specjalnie przez kompilator, gdy pojawiają się przed typem lub deklaracją z możliwością wywołania. W takim przypadku ich zawartość jest pobierana jako dokumentacja zdefiniowanego typu lub wywoływania, podobnie jak w przypadku innych języków platformy .NET.

W /// komentarzach tekst, który ma być częścią dokumentacji interfejsu API, jest formatowany jako Markdown, z różnymi częściami dokumentacji wskazanej przez specjalnie nazwane nagłówki. Jako rozszerzenie języka Markdown odwołania krzyżowe do operacji, funkcji i typów Q# zdefiniowanych przez użytkownika można uwzględnić przy użyciu @"<ref target>," metody , gdzie <ref target> jest zastępowana przez w pełni kwalifikowaną nazwę obiektu kodu, do którego się odwołuje. Opcjonalnie aparat dokumentacji może również obsługiwać dodatkowe rozszerzenia języka Markdown.

Przykład:

/// # 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# rozpoznaje następujące nazwy jako nagłówki komentarzy dokumentacji.

  • Podsumowanie: krótkie podsumowanie zachowania funkcji lub operacji lub przeznaczenia typu. Pierwszy akapit podsumowania jest używany do informacji o aktywowaniu wskaźnika myszy. Powinien to być zwykły tekst.
  • Opis: opis zachowania funkcji lub operacji lub przeznaczenia typu. Podsumowanie i opis są łączone w celu utworzenia wygenerowanego pliku dokumentacji dla funkcji, operacji lub typu. Opis może zawierać w wierszu symbole i równania w formacie LaTeX.
  • Dane wejściowe: opis krotki wejściowej dla operacji lub funkcji. Może zawierać dodatkowe podsekcje języka Markdown wskazujące każdy element krotki wejściowej.
  • Dane wyjściowe: opis krotki zwróconej przez operację lub funkcję.
  • Parametry typu: pusta sekcja zawierająca jedną dodatkową podsekcję dla każdego parametru typu ogólnego.
  • Nazwane elementy: opis nazwanych elementów w typie zdefiniowanym przez użytkownika. Może zawierać dodatkowe podsekcje języka Markdown z opisem każdego nazwanego elementu.
  • Przykład: krótki przykład operacji, funkcji lub typu używanego.
  • Uwagi: Różne proza opisujące jakiś aspekt operacji, funkcji lub typu.
  • Zobacz również: Lista w pełni kwalifikowanych nazw wskazujących powiązane funkcje, operacje lub typy zdefiniowane przez użytkownika.
  • Odwołania: lista odwołań i cytatów dla udokumentowanego elementu.