Equívocos comuns no uso do JSDoc
Abaixo podemos observar alguns equívocos comuns no uso do JSDoc, gerados por vícios do uso do JavaDoc, uso da API antiga de documentação e de algumas particularidades da implementação do JavaScript do sistema.
1) Uso de @type {Integer} ou @param {Integer}.
Não existe o construtor Integer no JavaScript. Utilize @type {Number} ou @param {Number}.
2) Uso da tag <optional> para indicar que um parâmetro é opcional. Exemplo:
* @param {Number} limite Indica a quantidade máxima de registros retornados.<optional>
A sintaxe para indicar um parâmetro opcional é colocá-lo dentro de colchetes. Exemplo correto:
* @param {Number} [limite] Indica a quantidade máxima de registros retornados.
3) Ausência da tag @example em trechos de códigos JavaScript. Exemplo:
/**
* Método que faz isto. Pode ser chamado desta forma:<br>
* if (x){<br>
* ds.append()<br>
* }<br>
* Ou desta forma:<br>
* if (x){<br>
* ds.append([10])<br>
* }
*/
Exemplo correto:
/**
* Método que faz isto.
* @example
* if (x){
* ds.append()
* }
* @example
* if (x){
* ds.append([10])
* }
*/
Códigos escritos dentro de uma tag @example respeitam o salto de linha e são exibidos dentro de uma caixa usando uma fonte de tamanho fixo, adequada para códigos fontes. Podem ser definidos quantos exemplos forem necessários.
4) Documentação dos métodos getters e setters. Exemplo:
/** @private */
MyFunction.prototype._x = 10
/**
* Altera o valor X.
* @param {Number} valor Valor a ser atualizado.
*/
MyFunction.prototype.setX = function (){
}
/**
* Pega o valor X.
* @return {Number} Valor x.
*/
MyFunction.prototype.getX = function (){
}
Exemplo correto:
/**
* Descrição de X.
* @type Number
*/
/*jsdoc MyFunction.prototype.x = 10 jsdoc*/
/** @private */
MyFunction.prototype._x = 10
/** @private */
MyFunction.prototype.setX = function (){
}
/** @private */
MyFunction.prototype.getX = function (){
}
5) Documentar o valor padrão de uma propriedade sem fazer uso da tag @default. Exemplo:
/**
* Propriedade X.<br>
* Valor padrão: 10.
* @type {Number}
*/
MyFunction.prototype.x = 10
Exemplo correto:
/**
* Propriedade X.
* @type {Number}
* @default 10
*/
MyFunction.prototype.x = 10
Recomendações finais:
A IDE do sistema possui templates mais frequentes do uso do JSDoc. Para utilizá-los escreva "doc" e pressione as teclas Ctrl + J;
Leia a documentação do JSDoc em http://usejsdoc.org/.