Partager via

Commentaires

  • Article

Les commentaires commencent par deux barres obliques (//) et continuent jusqu’à la fin de la ligne. Ces commentaires de fin de ligne peuvent apparaître n’importe où dans le code source. Q# ne prend actuellement pas en charge les commentaires de bloc.

Commentaires de documentation

Les commentaires qui commencent par trois barres obliques, ///, sont traités de manière spéciale par le compilateur quand ils apparaissent avant une déclaration de type ou de callable. Dans ce cas, leur contenu est utilisé comme documentation pour le type ou le callable défini, comme dans les autres langages .NET.

Dans les commentaires ///, le texte à afficher dans le cadre de la documentation d’API est au format Markdown, les différentes parties de la documentation étant indiquées par des en-têtes spécialement nommés. Parce qu’il s’agit d’une extension Markdown, vous pouvez ajouter des références croisées aux opérations, aux fonctions et aux types définis par l’utilisateur en Q# en utilisant @"<ref target>,", où <ref target> est remplacé par le nom complet de l’objet de code référencé. Un moteur de documentation peut également prendre en charge des extensions Markdown supplémentaires.

Par exemple :

/// # 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# reconnaît les noms suivants comme des en-têtes de commentaires de documentation.

  • Summary : bref récapitulatif du comportement d’une fonction ou d’une opération, ou de l’objectif d’un type. Le premier paragraphe du récapitulatif est utilisé pour les informations pointées. Il doit s’agir de texte brut.
  • Description : description du comportement d’une fonction ou d’une opération, ou de l’objectif d’un type. Le récapitulatif et la description sont concaténés pour former le fichier de documentation généré pour la fonction, l’opération ou le type. La description peut contenir des équations et des symboles au format LaTeX en ligne.
  • Input : description du tuple d’entrée d’une opération ou d’une fonction. Peut contenir des sous-sections Mardown supplémentaires indiquant chaque élément du tuple d’entrée.
  • Output : description du tuple retourné par une opération ou une fonction.
  • Paramètres de type : section vide qui contient une sous-section supplémentaire pour chaque paramètre de type générique.
  • Named Items : description des éléments nommés dans un type défini par l’utilisateur. Peut contenir des sous-sections Markdown supplémentaires avec la description de chaque élément nommé.
  • Example : exemple court de l’opération, de la fonction ou du type en cours d’utilisation.
  • Remarks : texte divers décrivant certains aspects de l’opération, de la fonction ou du type.
  • See Also : liste de noms complets indiquant les fonctions, opérations ou types définis par l’utilisateur associés.
  • References : liste de références et de citations pour l’élément documenté.