Как легко создать дружественную уценку 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, в котором я работал. Он работает достаточно хорошо для того, что мне нужно, хотя оно еще не близко к общей цели.

Так.....

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

Ответы

/**
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'