Как легко создать дружественную уценку Github для документированных функций JavaScript?

Я хочу иметь возможность принимать комментарии JSDoc, подобные этому в любом месте источника JavaScript (даже вложенные в несколько слоев функций, в модуль или даже анонимные функции):

/**
 *  Used to do some important thing that needs doing that works like xyz.
 *  @param {String} whatever - some string that has some purpose
 *  @param {Function} callback - a function that needs to be run
 *  @returns {Boolean} whether or not something happened
 */
 function something(whatever, callback) {
     ...

и у вас есть простой способ создать красивую уценку:

##`root.something(whatever,callback)`
Used to do some important thing that needs doing that works like xyz.

*Parameters*
  `whatever {String}` some string that has some purpose
  `callback {Function}` a function that needs to be run

*Returns*
   `{Boolean}` whether or not something happened

Где "root" - это пространство имен, доступное для этой функции. Или если это анонимная функция или частная функция (которая по какой-то причине должна быть в публичном doco, это даже имеет смысл?), Используйте другое соглашение, чтобы обозначить это. Может быть,

##_private_function_ `something(whatever,callback)`

  and

##_anonymous_function_`(whatever,callback)`

Это не должно быть именно этот формат, просто что-то, что хорошо выглядит на Github и имеет смысл. Идеальный инструмент был бы достаточно умным, чтобы иметь возможность принимать код типа Mustache.js и производить хороший результат. И дополнительным преимуществом было бы, если бы он мог обрабатывать множество исходных файлов и выводить один документ в качестве вывода или связанный набор документов в зависимости от конфигурации.

И было бы лучше, если бы это было сделано таким образом, чтобы его можно было полностью и легко включить в репозиторий git, чтобы люди не нуждались в настройке высокоспециализированной инструментальной цепочки для обновления doco. Или, по крайней мере, требуется минимальная инструментальная цепочка.

О, и пони.

Существующие параметры

JSDoc, а также некоторый вид преобразования HTML → markdown

JSDoc довольно хорош. Но я не могу показаться, что он хорошо работает с модулями. Вернее, это большая проблема, чем это должно быть ИМХО. Мне не нужно добавлять дополнительный тег, чтобы назвать функцию. Я пробовал @export и @name, и у меня все еще есть проблемы с тем, чтобы он отображался в конечном документе так, как я бы хотел. Если кто-то может указать на источник с комментариями JSDoc, в котором есть модули, и это сделано хорошо, это может помочь. Обновление: JSDoc v3 на самом деле кажется намного лучше с модулями, чем с v2, поэтому это может быть лучше.

Даже если бы я мог получить JSDoc-выход, как я хочу, мне нужно было бы преобразовать из HTML в уценку. Я не могу найти хороший инструмент для этого, существует ли он?

Docdown

Я немного поиграл с Docdown, но тот факт, что PHP для меня немного нестартер...

YUIDoc, а также конверсия

На самом деле я не играл с YUIDoc, но все выглядит нормально. Тем не менее, мне нужен конвертер. Легко ли это относится к модулю и не нужно явно указывать имя функции и имя экспорта?

Dox, плюс шаблоны уценки

Dox производит JSON по мере его вывода, поэтому вам нужно выйти замуж за некоторые хорошие шаблоны уценки, а также включить механизм создания шаблонов для создания документов. Кто-нибудь собрал набор таких шаблонов полезным способом?

jGrouse, а также конверсия

Работает с ANT. Далее...

ScriptDoc...

Это уже существует? Кажется, это часть студии Aptana, поэтому она была бы не стартовой... Аптана, похоже, не имеет никакой информации об этом. Но у ScriptDoc.org есть интересная информация о трещине, если это полезно...

Pdoc

Pdoc основан на Ruby, но эта инструментальная цепочка не является чем-то необычным, так что это не огромная проблема. Вы можете предоставить свои собственные шаблоны, поэтому, возможно, уже есть некоторые хорошие уценки. Я не играл с этим... это стоит? Есть ли хорошие шаблоны уценки?

Что-то еще?

Что еще там?

Сделайте свой собственный!

После того, как я несколько раз пытался работать с JSDoc, пытаясь заставить его работать так, как я хотел, я сдался и написал свое собственное быстрое и грязное решение в Java для CharFunk, javascript javascript, в котором я работал. Он работает достаточно хорошо для того, что мне нужно, хотя оно еще не близко к общей цели.

Так.....

Неужели это неудовлетворенная потребность или это только я?

Ответ 1

Вы пробовали jsdox?

Это node.js jsdoc для генератора уценки.

Ответ 2

Я использую jsdoc-to-markdown..

написать документированный код:

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

получить документы по уценке:

$ jsdoc2md example/function.js

#protection(cloak, dagger)
a quite wonderful function

**Params**

- cloak 'object' - privacy gown
- dagger 'object' - security

**Returns**: 'survival'

В этих проектах есть файлы readme, отрисованные jsdoc2md:

Ответ 3

markdox может генерировать документы разметки из кода javascript.

Ответ 4

jsDox. https://github.com/sutoiku/jsdox Полный анализ с использованием UglifyJS

СОТ. https://github.com/tjchaplin/mox Несколько готовых к запуску примеров/шаблонов.

Оба обрабатывают форматы JSDoc/Dox. Оба имеют активное развитие. Для меня Mox выигрывает из-за примера пакета.

Ответ 5

OK. После некоторого обсуждения с самим собой, я бы пошел с DOX + Underscore/Whatever JS templating engine над Node.

Должно быть довольно просто. Вы можете, возможно, даже застревать в Grunt или подобном, и запустить его под задачей просмотра.

Dox, из того, что я могу вспомнить, относительно легкий и имеет пакет npm (IIRC).

UPDATE: Я думаю, после некоторого опыта, что я хотел бы изменить свой ответ на YUIDoc.

Ответ 6

Попробуйте использовать Verb. В простейшем примере использования Verb будет строить readme из шаблона, используя данные из package.json.

Но у глагола также есть расширенные функции, если вам нужно создавать многостраничные TOC или создавать настраиваемые помощники и т.д.

Что касается документации API, см. этот пример readme, созданный с использованием комментариев кода от index.js. Нажмите на заголовки, они тоже автоматически сгенерированы. Используйте этот встроенный помощник для создания документов API из любого пути к файлу. Вы также можете использовать шаблоны glob, чтобы вытаскивать документы из нескольких файлов.

Глагол построит .verb.md без какой-либо конфигурации. Но если вам нужно больше, вы можете использовать verbfile.js

Ответ 7

Мне нужно было создать документацию по API из JSDoc, которая должна быть простой в использовании, а также поддерживает современные внешние стеки. Некоторые из упомянутых библиотек имеют проблемы с JS-кодом, переведенным в babeljs, поэтому вам нужно временно перекодировать код с комментариями, чтобы сгенерировать свою документацию по уценке.

В таком случае я нашел http://documentation.js.org/ весьма полезным, так как они интегрировали поддержку конфигураций BabelJs, поэтому он заботится о создании уценки ( JSON, HTML) из ваших JSDocs.