Я хочу иметь возможность принимать комментарии 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" - это пространство имен, в котором эта функция доступна. Или если это анонимная функция или частная функция (которая по какой-то причине должна быть в публичном документе, это даже делает смысл??), используйте какое-то другое соглашение, чтобы обозначить это. Может быть

##_private_function_ `something(whatever,callback)`



  and



##_anonymous_function_`(whatever,callback)`

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

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

О, и пони.

существующие варианты

JSDoc, плюс какой-то HTML - > markdown conversion

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

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

Docdown

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

YUIDoc плюс преобразования

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

здесь плюс шаблоны уценки

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

jGrouse плюс преобразования

работает с муравьем. Следующий...

ScriptDoc...

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

Pdoc

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

что-то еще?

что еще там?

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

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

так.....

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