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.