Или они и это просто не в источнике? Мне бы очень хотелось получить что-то, что остановит js-doc-toolkit от freaking каждый раз, когда он анализирует jQuery. Это также означает, что я не могу правильно документировать какой-либо код, используя jQuery в качестве зависимости, по крайней мере, не помещая некоторые шаблоны js-doc, которые не могут правильно документировать структуру jQuery. Есть ли общее решение, о котором я не знаю? Я пробовал искать походы, кстати.
Почему JQuery не использует JSDoc?
Ответ 1
Я сделаю снимок в темноте, так как я не могу говорить за команду 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 просто не работает здесь.
Ответ 2
Не знаю, почему они не добавляют комментарий JSDoc, но ребята Google Closure, похоже, сохраняют обновленную версию "externs", которая им нужна для компилятора закрытия с расширенной оптимизацией
http://code.google.com/p/closure-compiler/source/browse/trunk/contrib/externs/jquery-1.6.js?r=1152
Ответ 3
Пока я не могу добавить что-либо еще, что другие не имеют отношения к исходному вопросу, я могу предоставить ссылку на что-то, что МОЖЕТ автоматизировать документ jQuery.
Выполняет это, выполняя его в среде выполнения, а затем анализирует полученные деревья. Подобно JSDoc, он использует модифицированный Rhino. Это в зачаточном состоянии, но я надеюсь, что это кому-то пригодится.:)