Nodo de Documentación.js projects [closed]

Actualmente estoy usando JSDoc Toolkit para documentar mi código, pero no encaja del todo, es decir, parece tener dificultades para describir los espacios de nombres correctamente. Digamos que tienes 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 muestra simplemente como Foo y Bar, sin el encabezado database (o lib.database), que son bastante necesarios cuando no se tiene todo en un global alcance.

He intentado lanzar @namespace database y @name database.Foo en él, pero no resulta agradable.

Cualquier idea para hacer que la salida de JSDoc sea más adecuada, o alguna herramienta completamente diferente que funcione mejor con Node.js? (Miré brevemente en Natural Docs, JSDuck y breezed sobre bastantes otros que parecían bastante obsoletos...)

Author: Morten Siebuhr, 2011-05-23
Source

6 answers

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

Personalmente recomendaría usar docco para anotar su código fuente. Se pueden encontrar ejemplos para underscore, columna vertebral, docco .

Una buena alternativa a docco es groc

En cuanto a una documentación API real, personalmente encuentro que la documentación generada automáticamente a partir de comentarios simplemente no funciona para JavaScript y le recomendamos escribir a mano la documentación de la API.

Los ejemplos serían underscore API, API EXPRESS, API de nodejs, socket.io docs

Preguntas similares sobre StackOverFlow

 65
Author: Raynos,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2017-05-23 12:25:05

YUIDoc es un Nodo.aplicación js que genera documentación API a partir de comentarios en código fuente, utilizando una sintaxis similar a herramientas como Javadoc y Doxygen. YUIDoc proporciona:

  • Previsualizaciones en vivo. YUIDoc incluye un servidor de documentos independiente, por lo que es trivial obtener una vista previa de sus documentos mientras escribe.
  • Marcado moderno. La documentación generada por YUIDoc es una aplicación web atractiva y funcional con URLs reales y elegantes reservas para arañas y otros agentes que no pueden ejecutarse 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 lenguaje que soporte bloques /* */ comment.
 17
Author: Bill Gao,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2013-09-23 14:25:19

NOTA: Dox ya no produce HTML, sino un blob de JSON que describe el código analizado. Esto significa que el código a continuación ya no funciona terriblemente bien...

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

Hackeamos esto en nuestros makefiles: 

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 o más eficiente jamás hecha (y dox tiene bastantes bugs) - pero me parece que funciona bastante bien, al menos para proyectos menores.

 12
Author: Morten Siebuhr,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2014-12-18 14:59:29

Lo siento, no estaba 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 o no haber existido cuando hiciste tu pregunta.

 5
Author: John Freeman,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2012-03-13 15:53:48

Encontramos una solución muy buena para el problema: doxx.

Utiliza dox como se mencionó anteriormente y convierte esto a HTML agradable después. Tiene un buen uso y funcionó muy bien para mí.

Https://github.com/FGRibreau/doxx

 3
Author: Phil,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2013-04-14 05:41:11

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

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

Puedes también use el administrador de tareas GruntJS a través de grunt-groc ejemplo:

Instalar paquete:

npm install grunt-groc --save-dev

Configure en su archivo de tareas:

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'])

 2
Author: alejo8591,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2014-03-26 05:05:40