Или они есть и этого просто нет в исходниках? Мне бы очень хотелось получить что-то, что не даст js-doc-toolkit сходить с ума каждый раз, когда он анализирует jQuery. Это также означает, что я не могу должным образом задокументировать какой-либо код, использующий jQuery в качестве зависимости, по крайней мере, не поместив некоторые стандартные блоки js-doc, которые не могут должным образом документировать структуру jQuery. Есть ли какое-то общее решение, о котором я не знаю? Я пробовал гуглить, кстати.
Почему jQuery не использует JSDoc?
comment
Дубликат формата документации jQuery;) (увы, там нет ответа)
- person Marcel Korpel schedule 29.10.2010
comment
Небольшое обновление, но я обнаружил, что Docco гораздо проще документировать JS. Очень утомительно искать правильный тег JSDoc. Лично я нахожу стратегию документирования Docco более простой и реалистичной. Также есть Rocco, который, как жемчужина, будет лучше работать с Cygwin, поскольку NPM не т требуется.
- person hlfcoding schedule 06.08.2011
comment
Docco кажется хорошей идеей, за исключением одного: обрабатываются только однострочные комментарии — блочные комментарии игнорируются. Мне кажется, что блочные комментарии — это те, которые вам обязательно нужно обрабатывать, если вы пишете документацию по API, так как в них проще писать длинные пояснения.
- person user4815162342 schedule 11.09.2012
comment
@ user4815162342 На самом деле мне это нравится. Таким образом, я могу оставить многострочные комментарии только для аннотирования директив компилятора замыкания.
- person Camilo Martin schedule 26.09.2012
Ответы (3)
Я сделаю попытку в темноте, так как я не могу говорить от имени команды jQuery, почему я не буду использовать JSDoc. JSDoc, по крайней мере, в последний раз, когда я проверял, не имел никакого чистого способа поддержки перегрузки методов (или смещения параметров... как бы вы ни назвали его здесь), и jQuery использует это повсюду. Возьмем простой общий пример с .animate():
.animate({ height: 5 })
.animate({ height: 5 }, 100)
.animate({ height: 5 }, 100, "linear")
.animate({ height: 5 }, 100, "linear", func)
.animate({ height: 5 }, 100, func)
.animate({ height: 5 }, func)
.animate({ height: 5 }, { duration: 100, queue: false })
.animate({ height: 5 }, { duration: 100, easing: "linear" })
.animate({ height: 5 }, { duration: 100, easing: "linear", complete: func })
Все они допустимы, поскольку типы параметров проверяются и сдвигаются по мере необходимости. для поддержки как можно большего количества сценариев перегрузки... это просто чертовски запутывает JSDoc, нет простого способа добавить эти необязательные параметры в документацию. Пожалуйста, поправьте меня, если это изменилось, но в последний раз, когда я смотрел (и, вероятно, в последний раз, когда команда смотрела), это все еще было так.
Еще одно потенциальное соображение заключается в том, как генерируются некоторые методы при запуске jQuery, например (один из многих), почти все ярлыки обработчиков событий генерируются в цикле аналогичное поведение для других методов... как бы вы это задокументировали? Генерация JSDoc просто не работает здесь.
person
Nick Craver
schedule
29.10.2010
Я думаю, что невозможность документировать параметры, чтобы они были полностью правильными, не самая большая проблема. Меня больше беспокоит, почему сами объекты и методы нельзя по крайней мере задокументировать, чтобы JSDoc хотя бы знал, что они существуют и на что ссылаться. И одним из потенциальных преимуществ создания документов для проекта jQuery является более легкое обновление его с больших изменений до исходного кода jQuery. Есть ли лучший генератор документов? Я слышал о Докко...
- person hlfcoding; 29.10.2010
@hlfcoding - я не уверен, что есть лучшая альтернатива, честно говоря, большую часть времени я живу в Visual Studio, и есть предоставленный
-vsdos.js, который использует ... некоторые ребята из Microsoft или сообщество генерируют: stackoverflow.com/questions/2323366/jquery-1-4-2-vsdoc Редактор зависит от этой документации для сказать вам, что такое параметры, если они все время неточны (и несколько методов генерируются на лету... как вы документируете их в исходном коде?), то они не очень полезны.
- person Nick Craver; 29.10.2010
@Ник, мне просто интересно то же самое. Я использую файлы
-vsdoc.js и просто подумал: почему Microsoft должна делать это не так, как большинство? Я не думал, что это из-за «проверки типов» параметров jQuery. Хороший пример на этом фронте. Примечание: @hlfcoding имеет 666 точки повторения.
- person Jim Schubert; 05.07.2011
Это делает статическую проверку типов гораздо менее полезной, но эти перегрузки могут быть объявлены с помощью JSDoc: например, {string|Object|Number} — поэтому, если есть 5 параметров и все они могут быть сдвинуты, первый параметр заканчивается довольно сумасшедшим списком. из возможных типов. Вы можете использовать {*}, если это действительно может быть что угодно. Вы можете заставить каждую смену вызывать другую более строго типизированную функцию, чтобы отловить все проблемы статического типа, и надеяться, что Closure Compiler с ADVANCED_OPTIMIZATIONS встраивает достаточно вещей, чтобы устранить нагрузку на производительность, но это большая ставка и много дополнительной работы.
- person Chris Moschini; 20.10.2011
@Chris - это не совсем так, поскольку объявление типов таким образом приводит к множеству недопустимых комбинаций параметров. Например, параметр № 2 может быть функцией, но только в том случае, если параметр № 1 не является и т. д., поэтому объявление документов таким образом вводит в заблуждение и совершенно неверно в большинстве комбинаций. производить.
- person Nick Craver; 20.10.2011
Это предотвратило бы больше ошибочных случаев, чем вообще не применять к ним JSDoc. В конечном счете, смещение параметров в JQuery требует, чтобы компилятор фактически выполнил JS за несколько шагов, чтобы действительно определить, что является допустимым, а что нет. Похоже, что Closure или MS Ajax еще не делают этого.
- person Chris Moschini; 20.10.2011
@Chris - действительно, нет ... что также является еще одной причиной, по которой jQuery больше не использует Closure :)
- person Nick Craver; 20.10.2011
@Chris - JSDoc допускает необязательные параметры, заключая тип в квадратные скобки, например.
{[int]} duration. Это справится с перегрузкой, предполагая, что порядок непротиворечив. Однако он не справился бы с параметрами, помещенными в объект.
- person David Harkness; 25.06.2012
JSDoc также имеет тег
@variation, который полезен для документирования различных способов вызова метода.
- person kzh; 22.07.2013
Не знаю, почему они не добавляют комментарий JSDoc, но ребята из Google Closure, кажется, сохраняют обновленную версию «внешних», которые им нужны для компилятора закрытия с расширенной оптимизацией.
http://code.google.com/p/closure-compiler/source/browse/trunk/contrib/externs/jquery-1.6.js?r=1152
person
ʟɿʠʆɜʣʑɭʟʂɪəɬɸʛʌʢɑʓʔ
schedule
05.08.2011
Хотя я не могу добавить что-либо еще, чего не было у других относительно исходного вопроса, я могу предоставить ссылку на что-то, что МОЖЕТ автоматически документировать jQuery.
Он делает это, выполняя его в среде выполнения, а затем анализируя полученные деревья. Как и JSDoc, он использует модифицированный Rhino. Это в зачаточном состоянии, но я надеюсь, что это пригодится кому-то. :)
https://bitbucket.org/nexj/njsdoc
person
Jasmine Hegman
schedule
07.01.2013
JSDoc выполняет статический анализ.
- person kzh; 22.07.2013
Да. Я не говорил, что это не так, если вы так это восприняли. Я должен был пояснить здесь свою точку зрения, а именно то, что NJSDoc выполняет (динамический) анализ во время выполнения вместо статического анализа. Попытка достичь того же уровня (или выше) документации с меньшим количеством шаблонных подсказок (в идеале вообще без них).
- person Jasmine Hegman; 10.12.2013
