Compartir a través de

Comentarios

  • Artículo

Los comentarios comienzan con dos barras diagonales (//) y continúan hasta el final de la línea. Estos comentarios de fin de línea pueden aparecer en cualquier parte del código fuente. Q# actualmente no admite comentarios de bloque.

Comentarios de documentación

El compilador trata de forma especial los comentarios que comienzan con tres barras diagonales, ///, cuando aparecen antes de un tipo o declaración invocable. En ese caso, su contenido se toma como documentación para el tipo o invocable definido, igual que para otros lenguajes .NET.

Dentro de los comentarios ///, el texto que aparece como parte de la documentación de la API tiene el formato Markdown, con diferentes partes de la documentación indicadas por encabezados con nombre especial. Como extensión de Markdown, se pueden incluir referencias cruzadas a operaciones, funciones y tipos definidos por el usuario en Q# mediante @"<ref target>,", donde <ref target> se reemplaza por el nombre completo del objeto de código al que se hace referencia. Opcionalmente, un motor de documentación también puede admitir extensiones de Markdown adicionales.

Por ejemplo:

/// # 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# reconoce los nombres siguientes como encabezados de comentario de documentación.

  • Resumen: breve resumen del comportamiento de una función u operación o el propósito de un tipo. El primer párrafo del resumen se usa para mantener el puntero sobre la información. Debe ser texto sin formato.
  • Descripción: descripción del comportamiento de una función u operación, o el propósito de un tipo. El resumen y la descripción se concatenan para formar el archivo de documentación generado para la función, la operación o el tipo. La descripción puede contener símbolos y ecuaciones con formato LaTeX en línea.
  • Entrada: descripción de la tupla de entrada de una operación o función. Puede contener subsecciones de Markdown adicionales que indican cada elemento de la tupla de entrada.
  • Salida: descripción de la tupla devuelta por una operación o función.
  • Parámetros de tipo: sección vacía que contiene una subsección adicional para cada parámetro de tipo genérico.
  • Elementos con nombre: descripción de los elementos con nombre de un tipo definido por el usuario. Puede contener subsecciones de Markdown adicionales con la descripción de cada elemento con nombre.
  • Ejemplo: un breve ejemplo de la operación, función o tipo en uso.
  • Comentarios: narración variada que describe algún aspecto de la operación, función o tipo.
  • Vea también: una lista de nombres completos que indican funciones, operaciones o tipos definidos por el usuario relacionados.
  • Referencias: lista de referencias y referencias para el elemento documentado.