documentation - section - node js doc comment




Documentation des projets Node.js (4)

REMARQUE: Dox ne Dox plus de HTML, mais un blob de JSON décrivant le code analysé. Cela signifie que le code ci-dessous ne fonctionne plus très bien ...

Nous avons fini par utiliser Dox pour le moment. C'est un peu comme le docco , que Raynos mentionne, mais le tout en un seul fichier HTML pour la sortie.

Nous avons piraté ceci dans notre makefile s:

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" $^ > [email protected]

Ce n'est pas la documentation la plus jolie ou la plus efficace jamais réalisée (et dox a quelques bugs mineurs) - mais je trouve que cela fonctionne plutôt bien, du moins pour les projets mineurs.

J'utilise actuellement JSDoc Toolkit pour documenter mon code, mais cela ne correspond pas tout à fait - à savoir qu'il semble difficile de décrire correctement les espaces de noms. Disons que vous avez deux classes simples dans chacun de leurs fichiers:

lib/database/foo.js :

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

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

module.exports = foo;

Et puis quelque chose hérité lib/database/bar.js :

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

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

util.inherits(Bar, Foo);

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

Dans la documentation générée, ceci est simplement généré en tant que Foo et Bar , sans la database principale (ou lib.database ), ce qui est tout à fait nécessaire lorsque vous n’avez pas tout dans sa portée globale.

J'ai essayé de lancer la @namespace database et la @name database.Foo de @name database.Foo , mais ça ne se passe pas très bien.

Y a-t-il des idées pour rendre la sortie JSDoc plus adaptée ou un outil totalement différent qui fonctionne mieux avec Node.js? (J'ai brièvement regardé Natural Docs, JSDuck et j'ai survolé plusieurs autres qui avaient l'air assez obsolètes ...)


Désolé, je n'étais pas sur StackExchange il y a un an, mais je pense que la réponse à votre question initiale est d'utiliser la balise @memberOf:

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

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

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

Cette balise peut avoir existé ou non lorsque vous avez posé votre question.


JSDoc est un port de JavaDoc. Donc, fondamentalement, la documentation suppose une POO classique et cela ne convient pas à JavaScript.

Personnellement, je vous recommande d'utiliser docco pour annoter votre code source. On peut en trouver des exemples pour le underscore , la backbone et le docco .

Une bonne alternative au docco est groc

En ce qui concerne la documentation de l'API, je trouve personnellement que la documentation générée automatiquement à partir des commentaires ne fonctionne pas pour JavaScript et vous recommande de rédiger manuellement votre documentation API.

Exemples: API de soulignement, API Express, API nodejs , docs socket.io

Questions similaires sur


Je travaille avec JSDoc et est très efficace, en plus de la facilité, mais lorsque les projets ont beaucoup de bibliothèques alternatives sont un développement assez compliqué. J'ai trouvé Groc un très bon outil basé sur Docco et fonctionne avec d'autres langages tels que: Python, Ruby, C ++, entre autres ...

En outre, Groc fonctionne avec Markdown dans GitHub, ce qui peut être beaucoup plus efficace lorsque vous travaillez avec git en tant que contrôle de version. Aide à assembler des pages pour la publication sur GitHub.

Vous pouvez également utiliser le gestionnaire de tâches GruntJS via l'exemple grunt-groc :

Installer le paquet:

npm install grunt-groc --save-dev

configurez dans votre fichier de tâches:

grunt.loadNpmTasks('grunt-groc');

Et la tâche de configuration:

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

})

Pour la tâche d'exécution:

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