Документирование проектов Node.js

В настоящее время я использую JSDoc Toolkit для документирования моего кода, но он не совсем подходит - а именно, он, похоже, пытается описать пространства имен правильно. Скажем, у вас есть два простых класса в каждом из своих файлов:

lib/database/foo.js:

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

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

module.exports = foo;

А потом что-то унаследовало lib/database/bar.js:

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

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

util.inherits(Bar, Foo);

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

В сгенерированной документации это выводится просто как Foo и Bar, без ведущего database (или lib.database), что совершенно необходимо, если у вас нет всего в глобальной области.

Я пробовал бросать на него @namespace database и @name database.Foo, но это не получается приятно.

Любые идеи для того, чтобы сделать JSDoc вывод более подходящим, или какой-то совершенно другой инструмент, который лучше работает с Node.js? (Я ненадолго взглянул на Natural Docs, JSDuck и залез на несколько других, которые выглядели довольно устаревшими...)

Ответы

Ответ 1

ПРИМЕЧАНИЕ: Dox больше не выводит HTML, а blob JSON, описывающий проанализированный код. Это означает, что код ниже не работает ужасно хорошо...

В итоге мы использовали Dox. Это очень похоже на docco, о котором упоминает Raynos, но он все это в одном битном HTML файле для вывода.

Мы взломали это в наш 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]

Это не самая красивая или самая эффективная документация, когда-либо сделанная (и dox имеет немало мелких ошибок), но я считаю, что она работает довольно хорошо, по крайней мере для небольших проектов.

Ответ 2

JSDoc - это порт JavaDoc. Таким образом, в основном документация предполагает классический ООП и не подходит для JavaScript.

Лично я бы рекомендовал использовать docco для аннотирования исходного кода. Примеры этого можно найти для underscore, backbone, docco.

Хорошей альтернативой docco является groc

Что касается фактической документации API, я лично считаю, что автоматически созданная документация из комментариев просто не работает для JavaScript и рекомендует вам вручную написать документацию по API.

Примерами будут underscore API, Экспресс-API, nodejs API, socket.io docs

Похожие вопросы StackOverFlow

Создание документации Javascript

Ответ 3

YUIDoc - это приложение Node.js, которое генерирует документацию API из комментариев в источнике, используя синтаксис, похожий на такие инструменты, как Javadoc и Doxygen. YUIDoc обеспечивает:

Предварительный просмотр в реальном времени. YUIDoc включает автономный сервер doc, что делает его тривиальным для предварительного просмотра ваших документов при написании.
Современная разметка. Документация, созданная YUIDoc, представляет собой привлекательное функциональное веб-приложение с реальными URL-адресами и изящными резервными моментами для пауков и других агентов, которые не могут запускать JavaScript.
Поддержка широкого языка. YUIDoc был первоначально разработан для проекта YUI, но он не привязан к какой-либо конкретной библиотеке или языку программирования. Вы можете использовать его на любом языке, который поддерживает блоки /* */comment.

Ответ 4

Извините, я не был на StackExchange год назад, но я считаю, что ответ на ваш оригинальный вопрос заключается в использовании тега @memberOf:

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

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

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

Этот тег может существовать или отсутствовать, когда вы задали свой вопрос.

Ответ 5

Нашел действительно приятное решение проблемы: doxx.

Он использует dox, как упоминалось выше, и впоследствии преобразует его в хороший HTML. Имеет приятное использование и отлично работает для меня.

https://github.com/FGRibreau/doxx

Ответ 6

Я работаю с JSDoc и очень эффективен, в дополнение к легкому, но когда проекты имеют много альтернативных библиотек, это довольно сложная разработка. Я нашел Groc очень хороший инструмент на основе Docco и работает с другими языками, такими как: Python, Ruby, C + +, среди прочих...

Кроме того, Groc работает с Markdown в GitHub, который может быть намного более эффективным при работе с git в качестве контроля версий. Далее помогает сборка страниц для публикации на GitHub.

Вы также можете использовать диспетчер задач GruntJS через grunt-groc пример:

Установить пакет:

npm install grunt-groc --save-dev

настройте в своем файле задачи:

grunt.loadNpmTasks('grunt-groc');

И задача config:

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

});

Для задачи запуска:

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