Узел Документирования.проекты на 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 выводить что-то более подходящее, или какой-то совершенно другой инструмент, который лучше работает с узлом.Джей? (Я кратко посмотрел на Natural Docs, JSDuck и пронесся над несколькими другими, которые выглядели довольно устаревшими...)

6 57
node.js documentation code-documentation

6 ответов:

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

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

хорошей альтернативой docco является Грок

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

пример подчеркивание API,Express API,API на nodejs, socket.io docs

подобные вопросы StackOverFlow

65

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

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

Примечание: здесь больше не выводит HTML, а большой двоичный объект JSON, описывающий анализируемый код. Это означает, что приведенный ниже код больше не работает ужасно хорошо...

мы закончили с помощью здесь сейчас. Это очень похоже docco, что упоминает Raynos, но thows все это в одном битном HTML-файле для вывода.

Мы взломали их в 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" $^ > $@

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

12

Извините, я не был на 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

3

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

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

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

установка:

npm install grunt-groc --save-dev

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

grunt.loadNpmTasks('grunt-groc');

и задача конфигурации:

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

});

для выполнения задания:

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

2