typescript - planillas - plantillasco 50 cosas sobre mi si o no
¿Herramientas y guía para documentar el código TypeScript? (6)
Acabo de lanzar una herramienta llamada TypeDoc que genera páginas de documentación html api a partir de archivos TypeScript * .ts.
El generador de documentación ejecuta el compilador de TypeScript y extrae la información de tipo de los símbolos del compilador generados. Por lo tanto, no tiene que incluir ningún metadato adicional en sus comentarios.
Si quiere probarlo, simplemente instale y ejecute la herramienta a través de npm:
npm install typedoc --global
typedoc --out path/to/documentation/ path/to/typescript/project/
Si desea saber cómo es una documentación creada con TypeDoc, diríjase a la página de GitHub del proyecto:
¿Hay alguna herramienta para generar documentación para el código fuente de TypeScript? ¿O debería usar algo genérico como NaturalDocs? ¿Cuál sería el estilo recomendado de los comentarios de bloque / aquellos destinados para el volumen de documentación independiente?
Debería usar:
///<foo>bar</foo> MSVS kind of comments?
o
/** @javadoc style comments */
o quizás
/*
Something like this?
*/
Tengo miedo de usar /// porque se usa para importar, y no quiero pisar alguna otra característica futura posiblemente introducida de la misma manera, pero nunca se sabe ...
¿O es posible generar JavaScript documentado a partir de TypeScript y luego usar la cadena de herramientas de JavaScript?
Estoy compilando en JavaScript y uso jsduck ( https://github.com/senchalabs/jsduck ) para generar documentación api basada en los archivos JavaScript. Siempre y cuando no indique a tsc que elimine los comentarios que funcionen perfectamente, excepto los campos sin un valor predeterminado (!).
module example {
/**
* My class description
* @class example.MyClass
*/
export class MyClass {
/**
* Description of my property
* @property {String} myProperty
*/
myProperty: string = null;
/**
* This property will be removed in compiled JavaScript, that''s why
* this documentation will not be visible in jsduck.
*/
willNotWork: string;
/**
* Description of my method
* @method myFunction
* @param {String} myParam
*/
myFunction(myParam: string): void {
}
}
} // end of module
He escrito aquí una herramienta para generar documentación HTML a partir de archivos de declaración (.d.ts). Tiene soporte básico para comentarios estilo JSDoc.
Compile sus archivos fuente de TypeScript con las opciones -d -c para generar archivos de declaración y conservar los comentarios. Luego, después de la instalación, puedes ejecutar
typescript-docs *.d.ts
para generar documentación HTML en salida estándar.
Para guardar la salida en un archivo, use
typescript-docs *.d.ts --output=path/to/output.html
Puedes usar este tipo de comentarios encima de tu función.
/**
* Comment goes here
*/
Y a continuación, cuando llegue a su método, aparecerá la documentación.
Tal vez un poco tarde, pero después de encontrar este problema, descubrí que aún no había herramientas para hacerlo. Así que bifurqué el compilador TS y creé el código para hacerlo.
El proyecto del compilador de TypeScript bifurcado en v0.9.0.1 luego agregó una opción "--documentation" que generará la documentación wiki de cualquier JSDoc que ingrese en el código (no se requiere ninguno para la simple producción de métodos / propiedades, etc.)
Produce archivos .ts.wiki (cuyo contenido es adecuado para subirlos directamente a CodePlex, etc. si también usas los nuevos parámetros --wikiRemoveRoot y --wikiSourceRoot - ver fork - la descripción de mi primer commit). O podrías adaptar el código para producir HTML (lo que sería relativamente simple: he hecho el trabajo duro de manipular el compilador / delcrationEmitter :))
Espero que esto ayude (ya sea usted o futuros lectores de esta pregunta)
Ed
Generate XML Doc comenta uno de los problemas propuestos para el lenguaje TypeScript.
Por ahora, las herramientas de TypeScript admiten JSDoc Anunciando TypeScript 0.8.2 .
Entonces, definitivamente quieres usar el estilo JSDoc para comentarios. Si necesita comentarios solo para IntelliSense, el uso de JSDoc cubrirá sus necesidades. Si necesita comentarios porque desea proporcionar documentación para sus consumidores de API, debe usar archivos de declaración (* .d.ts) con comentarios. Si desea generar una buena documentación en la web, supongo que será fácil esperar cuando el equipo de TypeScript implemente la generación de comentarios de documentos XML (o escríbalos a mano).