Onde está documentada a sintaxe dos comentários do TypeScript?

165

A sintaxe dos comentários do TypeScript está documentada em algum lugar?

E, por acaso, agora ele suporta o ///sistema C # ?

David Thielen
fonte

Respostas:

61

A sintaxe correta agora é a usada pelo TSDoc . Isso permitirá que seus comentários sejam entendidos pelo Código do Visual Studio ou outras ferramentas de documentação.

Uma boa visão geral da sintaxe está disponível aqui e especialmente aqui . A especificação precisa deve ser "em breve" escrita .

Outro arquivo que vale a pena conferir é este, onde você verá tags padrão úteis.

Nota : você não deve usar o JSDoc, conforme explicado na página principal do TSDoc: Por que o JSDoc não pode ser o padrão? Infelizmente, a gramática JSDoc não é rigorosamente especificada, mas inferida do comportamento de uma implementação específica. A maioria das tags JSDoc padrão está preocupada em fornecer anotações de tipo para JavaScript simples, o que é uma preocupação irrelevante para uma linguagem fortemente tipada como o TypeScript. O TSDoc aborda essas limitações enquanto também aborda um conjunto de objetivos mais sofisticados.

Qortex
fonte
177

Futuro

A equipe do TypeScript e outras equipes envolvidas do TypeScript planejam criar uma especificação formal padrão do TSDoc. O 1.0.0rascunho ainda não foi finalizado: https://github.com/Microsoft/tsdoc#where-are-we-on-the-roadmap

insira a descrição da imagem aqui

Atual

TypeScript usa JSDoc. por exemplo

/** This is a description of the foo function. */
function foo() {
}

Para aprender jsdoc: https://jsdoc.app/

Demo

Mas você não precisa usar as extensões de anotação de tipo no JSDoc.

Você pode (e deve) ainda usar outras tags de bloco jsdoc como @returnsetc.

Exemplo

Apenas um exemplo. Concentre-se nos tipos (não no conteúdo).

Versão JSDoc (tipos de aviso nos documentos):

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}

Versão TypeScript (observe a nova localização dos tipos):

/**
 * Takes two numbers and returns their sum
 * @param a first input to sum
 * @param b second input to sum
 * @returns sum of a and b
 */
function sum(a: number, b: number): number {
    return a + b;
}
basarat
fonte
1
Como Bas diz! Para um bom exemplo de uso confira jQuery.d.ts do DefinitelyTyped
John Reilly
1
que, é claro, foi publicada por @JohnnyReilly! :) github.com/borisyankov/DefinitelyTyped/blame/master/jquery/…
basarat
14
Esta não é uma boa "melhor resposta", pois não explica parâmetros, propriedades e valores de retorno.
Piranha
5
Isso não está mais atualizado. Veja a resposta atualizada abaixo.
Qortex
59

Você pode adicionar informações sobre parâmetros, retornos etc., também usando:

/**
* This is the foo function
* @param bar This is the bar parameter
* @returns returns a string version of bar
*/
function foo(bar: number): string {
    return bar.toString()
}

Isso fará com que editores como o VS Code o exibam da seguinte maneira:

insira a descrição da imagem aqui

Sharpiro
fonte
1
Do u sei a tecla de atalho para isso em VSCODE
jet_choong
3
Se você começar a digitar /**, em seguida, prima tabem uma linha acima da função, vs-code auxilia-lo a preencher o comentário JSDoc com parâmetros
Sharpiro
14

Você pode usar comentários como no JavaScript comum:

A sintaxe do TypeScript é um superconjunto da sintaxe do Ecmascript 5 (ES5). [...]

Este documento descreve a gramática sintática adicionada pelo TypeScript

Fora isso, eu só achei isso sobre comentários nas especificações de idioma:

O TypeScript também fornece aos programadores de JavaScript um sistema de anotações de tipo opcionais . Essas anotações de tipo são como os comentários JSDoc encontrados no sistema Closure, mas no TypeScript eles são integrados diretamente à sintaxe da linguagem. Essa integração torna o código mais legível e reduz o custo de manutenção da sincronização de anotações de tipo com suas variáveis ​​correspondentes.

11.1.1 Dependências dos arquivos de origem:

Um comentário do formulário /// <reference path="..."/>adiciona uma dependência no arquivo de origem especificado no argumento path. O caminho é resolvido em relação ao diretório do arquivo de origem que contém

Fonte:
https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md

CodeManX
fonte
O link de origem está quebrado.
Pavlo 23/01
1
Substituído por um link para a fonte de especificações no GitHub. Também disponível como documentos em Word e PDF: github.com/Microsoft/TypeScript/tree/master/doc
CodeManX
3

TypeScript é um superconjunto sintático estrito de JavaScript, portanto,

  • Os comentários de linha única começam com //
  • Os comentários de várias linhas começam com / * e terminam com * /
Ayushi Jain
fonte