Compartilhar via


Comentários

Os comentários começam com duas barras (//) e continuam até o final da linha. Esses comentários de fim da linha podem aparecer em qualquer lugar no código-fonte. Atualmente, Q# não dá suporte a comentários de bloco.

Comentários de documentação

Comentários que começam com três barras, ///, são tratados especialmente pelo compilador quando aparecem antes de um tipo ou declaração chamável. Nesse caso, o conteúdo é levado como documentação para o tipo definido ou chamável, como para outras linguagens .NET.

Nos comentários do ///, o texto a ser exibido como parte da documentação da API é formatado como Markdown, com diferentes partes da documentação indicadas por cabeçalhos especialmente nomeados. Como uma extensão para Markdown, referências cruzadas para operações, funções e tipos definidos pelo usuário em Q# podem ser incluídas usando @"<ref target>,", em que <ref target> é substituído pelo nome totalmente qualificado do objeto de código que está sendo referenciado. Opcionalmente, um mecanismo de documentação também pode dar suporte a extensões adicionais do Markdown.

Por exemplo:

/// # 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);
}

O Q# reconhece os nomes a seguir como cabeçalhos de comentário de documentação.

  • Resumo: um breve resumo do comportamento de uma função ou operação ou da finalidade de um tipo. O primeiro parágrafo do resumo é usado para informações de foco. Ele deve conter texto sem formatação.
  • Descrição: uma descrição do comportamento de uma função ou operação ou a finalidade de um tipo. O resumo e a descrição são concatenados para formar o arquivo de documentação gerado para a função, a operação ou o tipo. A descrição pode conter equações e símbolos formatados em LaTeX em linha.
  • Entrada: uma descrição da tupla de entrada para uma operação ou função. Pode conter subseções de Markdown adicionais que indicam cada elemento da tupla de entrada.
  • Saída: uma descrição da tupla retornada para uma operação ou função.
  • Parâmetros de tipo: uma seção vazia que contém uma subseção adicional para cada parâmetro de tipo genérico.
  • Itens nomeados: uma descrição dos itens nomeados em um tipo definido pelo usuário. Pode conter subseções adicionais de Markdown com a descrição de cada item nomeado.
  • Exemplo: um breve exemplo da operação, da função ou do tipo em uso.
  • Comentários: diversos trechos que descrevem algum aspecto da operação, função ou tipo.
  • Confira Também: uma lista de nomes totalmente qualificados que indicam funções, operações ou tipos definidos pelo usuário relacionados.
  • Referências: uma lista de referências e citações para o item documentado.