documentation - comment - Documentación de proyectos de Node.js

node js documentation generator

Question

Actualmente estoy usando JSDoc Toolkit para documentar mi código, pero no encaja del todo, es decir, me parece difícil describir correctamente los espacios de nombres. Supongamos que tiene dos clases simples en cada uno de sus archivos:

lib/database/foo.js :

/** @class */
function Foo(...) {...}

/** @function ... */
Foo.prototype.init(..., cb) { return cb(null, ...); };

module.exports = foo;

Y luego algo heredado lib/database/bar.js :

var Foo = require(''./foo'');

/**
 * @class
 * @augments Foo
 */
function Bar(....) {...}

util.inherits(Bar, Foo);

Bar.prototype.moreInit(..., cb) { return cb(null, ...); };

En la documentación generada, esto se genera simplemente como Foo y Bar , sin la database principal (o lib.database ), que son bastante necesarias cuando no se tiene todo en un ámbito global.

Intenté arrojar la @namespace database y la @name database.Foo de @name database.Foo , pero no salió bien.

¿Alguna idea para hacer que JSDoc genere algo más adecuado, o alguna herramienta completamente diferente que funcione mejor con Node.js? (Miré brevemente a Natural Docs, JSDuck y revisé varios otros que parecían bastante obsoletos ...)

Answer 1

NOTA: Dox ya no emite HTML, sino una burbuja de JSON que describe el código analizado. Esto significa que el código siguiente ya no funciona terriblemente bien ...

Terminamos usando Dox por ahora. Es muy parecido a docco , que Raynos menciona, pero lo lanza todo en un archivo HTML de un bit para la salida.

Hemos pirateado esto en nuestro makefile :

JS_FILES := $(shell find lib/ -type f -name /*.js | grep -v 3rdparty)

#Add node_modules/*/bin/ to path:
#Ugly ''subst'' hack: Check the Make Manual section 8.1 - Function Call Syntax
NPM_BINS:=$(subst bin node,bin:node,$(shell find node_modules/ -name bin -type d))
ifneq ($(NPM_BINS),) 
    PATH:=${NPM_BINS}:${PATH}
endif

.PHONY: doc lint test

doc: doc/index.html

doc/index.html: $(JS_FILES)
    @mkdir -p doc
    dox --title "Project Name" $^ > $@

No es la documentación más bonita ni la más eficiente jamás realizada (y dox tiene bastantes errores menores), pero creo que funciona bastante bien, al menos para proyectos menores.

Answer 2

Encontré una solución realmente buena para el problema: doxx.

Utiliza dox como se menciona anteriormente y luego lo convierte en un bonito HTML. Tiene un buen uso y funcionó muy bien para mí.

https://github.com/FGRibreau/doxx

Answer 3

JSDoc es un puerto de JavaDoc. Así que, básicamente, la documentación supone OOP clásico y eso no es adecuado para JavaScript.

Personalmente, recomendaría usar docco para anotar tu código fuente. Se pueden encontrar ejemplos de él para underscore , backbone , docco .

Una buena alternativa al docco es groc

En cuanto a la documentación real de la API, personalmente encuentro que la documentación generada automáticamente a partir de los comentarios simplemente no funciona para JavaScript y recomiendo que escribas a mano la documentación de tu API.

Algunos ejemplos serían la API de subrayado , API Express , API de nodejs , documentos de socket.io

Preguntas similares sobre

• Generando documentación de Javascript

Answer 4

Lo siento, no estuve en StackExchange hace un año, pero creo que la respuesta a su pregunta original es usar la etiqueta @memberOf:

/** @namespace */
database = {};

/**
 * @class
 * @memberOf database
 */
function Foo() { ... };

http://code.google.com/p/jsdoc-toolkit/wiki/TagMemberOf

Esta etiqueta puede haber existido o no cuando usted hizo su pregunta.

Answer 5

Trabajo con JSDoc y es muy eficiente, además de fácil, pero cuando los proyectos tienen muchas bibliotecas alternativas, el desarrollo es bastante complicado. Encontré Groc una herramienta muy buena basada en Docco y funciona con otros lenguajes como: Python, Ruby, C + +, entre otros ...

Además Groc trabaja con Markdown en GitHub que puede ser mucho más eficiente cuando se trabaja con git como control de versiones. Además ayuda a armar páginas para publicar en GitHub.

También puede usar el administrador de tareas GruntJS través grunt-groc ejemplo de grunt-groc :

Paquete de instalación:

npm install grunt-groc --save-dev

configurar en su archivo de tarea:

grunt.loadNpmTasks(''grunt-groc'');

Y la tarea de configuración:

// Project configuration.
grunt.initConfig({
   groc: {
    coffeescript: [
       "coffee/*.coffee", "README.md"
   ],
    options: {
       "out": "doc/"
   }
 }

});

Para ejecutar la tarea:

grunt.registerTask(''doc'', [''groc''])

Answer 6

YUIDoc es una aplicación Node.js que genera documentación API a partir de comentarios en el origen, utilizando una sintaxis similar a herramientas como Javadoc y Doxygen. YUIDoc proporciona:

• Vistas previas en vivo. YUIDoc incluye un servidor doc independiente, por lo que es trivial obtener una vista previa de sus documentos a medida que escribe.
• Marcado moderno. La documentación generada por YUIDoc es una aplicación web atractiva y funcional con URL reales y elegantes inconvenientes para arañas y otros agentes que no pueden ejecutar JavaScript.
• Amplio soporte de idiomas YUIDoc fue diseñado originalmente para el proyecto YUI, pero no está vinculado a ninguna biblioteca o lenguaje de programación en particular. Puede usarlo con cualquier idioma que admita bloques / * * / comment.