Есть ли стандарт JSDoc?

Я знаю, что вокруг JSDoc есть разные вкусы. И кажется, что каждая реализация парсера JSDoc распознает собственный набор тегов. Например, рассмотрите различия в тегах между http://usejsdoc.org/ и http://www.techrepublic.com/blog/programming-and-development/create-useful-relevant-javascript-documentation-with-jsdoc/451.

В этот момент я просто смущен. Существует ли каноническая реализация JSDoc или широко признанного набора основных тегов? Есть ли лучшая реализация JSDoc?

ИЗМЕНИТЬ

Как указано в комментарии ниже, причина этого вопроса в том, что мне нужно разобрать комментарии JSDoc для использования с инструментом, который мы создаем. См. Этот вопрос ": Есть ли открытый JSDoc-анализатор с открытым исходным кодом, написанный на Javascript?

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

Но, на более глубоком уровне, он касается меня тем, что нет согласованной спецификации (или эталонной реализации). Это заставляет JSDoc чувствовать себя немного ad hoc для меня.

Ответ 1

Тот, который, по моему мнению, является наиболее полным, является тем, который используется компилятором google

Одной из замечательных особенностей использования компилятора google закрытия является то, что он будет проверять тип ваших функций, которые были помечены информацией о типе.

Я чувствую твою боль, я занимаюсь этим весь день. Вот пример нестандартной функции, которую я должен использовать для кода/документа. Ext-JS использует @cfg для документирования свойств объекта инициализации, который вы передаете в виджет. В IDE, который я использую, IntelliJ, использует JSDoc для обеспечения лучших предложений кода, и он даже понимает диалект Ext. Для большинства вещей он работает хорошо. Тем не менее, много раз мне приходится дублировать документацию как-то, чтобы понять как ее IDE, так и инструмент doc (Ext-версия jsdoc), не очень DRY. Вот один пример:

...
/** 
 * @cfg {string} title // Ext-JS grabs the type from this line
 * @type string // My IDE grabs the type from this line
 */
 title: null // My IDE requires this line to recognize the cfg
             // as a property of the object even though all cfgs
             // are available in the object
...

Ответ 2

Я тоже разделяю вашу боль. Это раздражает, что это не стандартизировано. Хотя я согласен с г-ном Хуаном Мендесом в том, что функции Closure Compiler являются наиболее полными (и, вероятно, самыми удивительными!),

Я всегда думал о списке тегов, найденном здесь http://code.google.com/p/jsdoc-toolkit/w/list, как самое близкое, что мы имеем к реальной спецификации. Он может быть устаревшим, но все же он может быть ближе к тому, что реализовано многими синтаксическими анализаторами и IDE, иначе чем Closure Compiler будет.

См. также Википедию для минимального консенсуса относительно того, какие метки должны быть там. http://en.wikipedia.org/wiki/JSDoc

Хотя, если ваш продукт поддерживает вкус компилятора Closure JSDoc, это приблизит его на один шаг к тому, чтобы стать стандартом defacto.: D