web-dev-qa-db-fra.com

Documentation des projets Node.js

J'utilise actuellement JSDoc Toolkit pour documenter mon code, mais il ne correspond pas tout à fait - à savoir, il semble avoir du mal à décrire correctement les espaces de noms. Supposons que vous ayez 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 a 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 sorti en tant que Foo et Bar, sans le premier database (ou lib.database), qui sont tout à fait nécessaires lorsque vous n'avez pas tout dans une portée globale.

J'ai essayé de lancer @namespace database et @name database.Foo à elle, mais il ne se révèle pas agréable.

Avez-vous des idées pour rendre la sortie JSDoc quelque chose de plus approprié, ou un outil entièrement différent qui fonctionne mieux avec Node.js? (J'ai regardé brièvement Natural Docs, JSDuck et j'ai survolé plusieurs autres qui avaient l'air assez obsolètes ...)

documentationnode.jscode-documentation
58
Morten Siebuhr

REMARQUE: Dox ne produit plus de code 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 l'instant. C'est un peu comme docco , que Raynos mentionne, mais qui le montre en un seul fichier HTML pour la sortie.

Nous avons piraté cela dans nos 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" $^ > $@

Ce n'est pas la documentation la plus jolie ou la plus efficace jamais faite (et dox a pas mal de bugs mineurs) - mais je trouve que ça marche plutôt bien, au moins pour les projets mineurs.

12
Morten Siebuhr

JSDoc est un portage de JavaDoc. Donc, fondamentalement, la documentation suppose classique OOP et ce n'est pas adapté à JavaScript.

Personnellement, je recommanderais d'utiliser docco pour annoter votre code source. Des exemples peuvent être trouvés pour souligné , backbone , docco .

Une bonne alternative au docco est groc

En ce qui concerne une documentation API réelle, je trouve personnellement que la documentation générée automatiquement à partir des commentaires ne fonctionne tout simplement pas pour JavaScript et je vous recommande d'écrire à la main votre documentation API.

Les exemples seraient API de soulignement , API Express , API nodejs , socket.io docs

Questions StackOverFlow similaires

69
Raynos

YUIDoc est une application Node.js qui génère la documentation de l'API à partir des commentaires dans la source, en utilisant une syntaxe similaire à des outils comme Javadoc et Doxygen. YUIDoc fournit:

  • Aperçus en direct. YUIDoc inclut un serveur de documentation autonome, ce qui rend trivial la prévisualisation de vos documents pendant que vous écrivez.
  • Balisage moderne. La documentation générée par YUIDoc est une application Web fonctionnelle et attrayante avec de vraies URL et des solutions de rechange gracieuses pour les araignées et autres agents qui ne peuvent pas exécuter JavaScript.
  • Large prise en charge des langues. YUIDoc a été initialement conçu pour le projet YUI, mais il n'est lié à aucune bibliothèque ou langage de programmation particulier. Vous pouvez l'utiliser avec n'importe quelle langue prenant en charge les blocs de commentaires/* * /.
17
Bill Gao

Désolé, je n'étais pas sur StackExchange il y a un an, mais je pense que la réponse à votre question d'origine 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 ou non exister lorsque vous avez posé votre question.

5
John Freeman

J'ai trouvé une solution vraiment sympa au problème: doxx.

Il utilise dox comme mentionné ci-dessus et le convertit ensuite en Nice HTML. A une utilisation agréable et a très bien fonctionné pour moi.

https://github.com/FGRibreau/doxx

3
Phil

Je travaille avec JSDoc et est très efficace, en plus d'être simple, mais lorsque les projets ont de nombreuses bibliothèques alternatives, le développement est assez compliqué. J'ai trouvé Groc un très bon outil basé sur Docco et qui fonctionne avec d'autres langages comme: Python, Ruby, C++, entre autres ...

De plus, Groc fonctionne avec Markdown dans GitHub, ce qui peut être beaucoup plus efficace lorsque vous travaillez avec git comme contrôle de version. Aide également à assembler des pages pour les publier sur GitHub.

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

Installer le paquet:

npm install grunt-groc --save-dev

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

2
alejo8591