Comentários

Os comentários começam com dois cortes para a frente (//) e continuam até ao fim da linha. Tais comentários finais podem aparecer em qualquer lugar do código de origem. Q# não suporta atualmente comentários de bloco.

Comentários de documentação

Comentários que começam com três cortes dianteiros, ///são tratados especialmente pelo compilador quando aparecem antes de um tipo ou declaração callable. Nesse caso, os seus conteúdos são tomados como documentação para o tipo definido ou callable, como para outras línguas .NET.

Dentro de /// comentários, o texto a aparecer como parte da documentação da API é formatado como Markdown, com diferentes partes da documentação indicada por cabeçalhos especialmente nomeados. Como extensão a Markdown, podem incluir referências cruzadas a operações, funções e tipos definidos pelo utilizador, Q# utilizando @"<ref target>," o local onde <ref target> é substituído pelo nome totalmente qualificado do objeto de código que está a ser referenciado. Opcionalmente, um motor de documentação também pode suportar extensões adicionais de 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);
}

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

• Resumo: Um breve resumo do comportamento de uma função ou operação ou o propósito de um tipo. O primeiro parágrafo do resumo é utilizado para informações sobre hover. Devia ser um texto simples.
• Descrição: Descrição do comportamento de uma função ou operação ou do propósito de um tipo. O resumo e a descrição são concatenados para formar o ficheiro de documentação gerada para a função, operação ou tipo. A descrição pode conter símbolos e equações formatados em linha laTeX.
• Entrada: Descrição do tuple de entrada para uma operação ou função. Pode conter subsecções de markdown adicionais que indiquem cada elemento do tuple de entrada.
• Saída: Uma descrição do tuple devolvido por uma operação ou função.
• Parâmetros do tipo: Uma secção vazia que contém uma subsecção adicional para cada parâmetro genérico do tipo.
• Itens nomeados: Uma descrição dos itens nomeados num tipo definido pelo utilizador. Pode conter subsecções markdown adicionais com a descrição de cada item nomeado.
• Exemplo: Um pequeno exemplo da operação, função ou tipo de utilização.
• Observações: Prosa diversa descrevendo algum aspeto da operação, função ou tipo.
• Consulte também: Uma lista de nomes totalmente qualificados que indiquem funções, operações ou tipos definidos pelo utilizador.
• Referências: Uma lista de referências e citações para o item documentado.