Ответ 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 просто не работает здесь.