Генераторы документации ECMAScript 6

Ответ 1

В настоящее время существует несколько генераторов документации ES6. В настоящее время я рекомендую ESDoc, поскольку в настоящее время это самый полный генератор документации.

Я обновлю это при необходимости.

ESDoc

ESDoc поддерживает синтаксис JSDoc, анализирует большинство (или все?) ES6 и выводит красивые HTML-документы. ESDoc настроен с использованием файла esdoc.json и может документировать целые каталоги. Он интегрирует Mocha для генерации покрытия. Также есть выход JSON.

Docchi

Docchi работает только с одним файлом и выдает файл JSON, который описывает код JavaScript. Он не создает HTML или другие обработанные документы и не утверждает, что он не соответствует многим узлам AST. Но он использует тот же вид JSON, что и Dox, чтобы можно было использовать те же самые зрители, что и для Dox.

JSDoc

JSDoc полностью поддерживает ES 6 и понимает помимо этого много синтаксиса, который анализируется Babel.

Transcription

Транскрипция была попыткой написать генератор документации ES6, но последняя фиксация - с 16 марта 2015 года.

YUIDoc

YUIDoc частично поддерживает ES6.

documentationjs

Documentationjs - это новый генератор документации. Он поддерживает ES6 и позволяет вам писать ваши комментарии в стандартном формате JSDoc.

Ответ 2

Я также потратил время на поиск приличного генератора документации ES6 и ничего не нашел, поэтому начал писать свой собственный Transcription. Он даже не близок к проверке корректно, но он работает с одиночными файлами и выводит JSON, Markdown и HTML (в этот момент он не очень стильный и очень простой).

Для всех, кто заинтересован в выполнении чего-то подобного, Acorn (для представления кода как объектов JavaScript) и Doctrine (для обработки блоков комментариев и доклетов) - это несколько библиотек, которые вам очень помогут.

Если вы хотите увидеть, что он генерирует против класса образца, это должно начать:

• git clone https://github.com/affirmix/transcription.git
• cd transcription
• npm install
• gulp
• Одна из следующих команд: (Для JSON, Markdown и HTML соответственно)
  • node dist/app.js ./input -f json -o ./output.json
  • node dist/app.js ./input -f md -o ./output
  • node dist/app.js ./input -f html -t ./jade -o ./output

Ответ 3

Если инструмент сборки является опцией, я бы поместил источник в transpiler es6 (babel), а затем передал результат в генератор jsdoc. Поэтому ANY синтаксис es6 может поддерживаться без ожидания поддержки встроенного JSDOC.

Вот пример использования node.js и gulp:

var gulp = require('gulp');
var babel = require('gulp-babel');
var jsdoc = require('gulp-jsdoc');

gulp.task('jsdoc', function() {
  return gulp.src('**/*.js')
    .pipe(babel())
    .pipe(jsdoc.parser())
    .pipe(jsdoc.generator('./docs'));
});

И вот рабочий исходный код в проекте webapplate

Ответ 4

Вы можете сказать JSDoc игнорировать все, что не является комментарием /**, не позволяя ему вызывать ошибки синтаксического анализа.

Это означает, что JSDoc не будет пытаться выполнять какую-либо интерпретацию кода, но я обнаружил, что в любом случае вам нужно быть довольно подробным с комментариями JSDoc. Здесь пример с использованием node.js и gulp:

var gulp = require('gulp');
var jsdoc = require('gulp-jsdoc');

gulp.task('jsdoc', function() {
    return gulp.src('./client/**.js')
        .pipe(jsdoc.parser({plugins: ['plugins/commentsOnly']}))
        .pipe(jsdoc.generator('./doc'));
});

gulp.task('default', ['jsdoc']);

Это не идеальное решение, но оно позволяет вам иметь документацию в стиле JavaDoc для вашего кода ES6 без необходимости переходить через обручи.

Примечание. В плагине commentsOnly есть известная ошибка, из-за которой он не удаляет код из файлов с нулевыми комментариями. Я отправил запрос на перенос, и он исправлен в последней версии JSDoc, но gulp-jsdoc не обновил свои зависимости и, вероятно, не будет в ближайшем будущем.

Чтобы исправить это, убедитесь, что каждый отдельный файл имеет хотя бы один комментарий /** или исправляет плагин вручную. Плагин можно найти в node_modules/gulp-jsdoc/node_modules/jsdoc/plugins/commentsOnly.js. Это:

if (comments) {
    e.source = comments.join('\n\n');
}

должен быть:

if (comments) {
    e.source = comments.join('\n\n');
} else {
    e.source = ''; // If file has no comments, parser should still receive no code
}

Ответ 5

Кажется, что поддержка синтаксиса класса в течение нескольких недель теперь https://github.com/jsdoc3/jsdoc/issues/555#issuecomment-83232420 (инструкции по установке master https://github.com/jsdoc3/jsdoc) - я дам ему ответ и отчитаюсь (все кажется, что он поворачивается на node возможность разбора ES6).

Ответ 6

Я рекомендую jsdoc3 (usejsdoc.org) в основном потому, что он, по-видимому, является стандартом "defacto" для проверки типов JavaScript и автозаполнения в IDE, таких как визуальный код студии, webstorm, netbeans, eclipse и т.д. В общем, вы можете из преимуществ типизированных языков, таких как typescript или поток, но 100% с ванильным JavaScript. Кроме того, проверка типов в среде IDE идеально подходит для синхронизации кода и jsdocs.

Кстати, я автор https://github.com/cancerberoSgx/short-jsdoc, потому что мне не понравился синтаксис любого из текущих решений, поэтому он определяет меньший/интуитивный/простой синтаксис и добавляет много недостающих функций. Но в крупных/общественных проектах /API я использую jsdoc3 по причинам, указанным выше.