Пытаюсь освоить JSDoc. Синтаксис и поведение буквально потрясают своей исключительной нелогичностью. Аж диву даёшься, насколько неочевидным способом там документируются даже простейшие вещи.
Поскольку запасы мата в адрес разработчиков уже подходят к концу, хотелось бы посмотреть примеры гуру.
Подскажите достаточно сложный проект, который бы документировался с использованием данного инструмента. Идеально, если это будет навороченная библиотека, по богатству функций мало уступающая jQuery. И, естественно, с открытыми исходниками, чтоб можно было посмотреть, как там внутри всё это документируется.
ngDoc базируется на jsDoc, и расширяет его своими директивами, которые нужны для упрощения указания на какие-то специфичные особенности, вроде, использует данная директива изолированные скоупы или нет. Обычно в проектах подобных надстроек ненужно, тут же это используется часто, потому проще вынести.
ngDoc выглядит довольно привлекательно, определённо стоит его попробовать. Спасибо за наводку.
А вот аннотации в AngularJS, как оказалось, удивительно простые. Там не документируется каких-либо сложных абстракций, и даже иерархии классов не задокументированы.
что в jsdoc такого сложного, что нужно ругаться матом
Кажется, JSDoc плохо приспособлен для документирования мало-мальски сложных абстракций.
Например, как там задокументировать такую простейшую вещь, как передачу namespace'а в функцию?
var LSTree;
(function(ns) {
//...
})(LSTree||LSTree={});
Если так сделать, то документирование объектов внутри LSTree становится весьма мучительным (на stackoverflow уже изобрели тонны костылей на такой случай).
Плюс неадекватное поведение, когда он упорно суёт объекты/методы не в тот namespace в случае вложенных namespace'ов, яростно сопротивляется любым попыткам задекларировать instance-методы (@instance приводит к тому, что коммент к методу вообще не создаётся, @name в связке с @memberof вызывают дикие глюки с документацией класса, когда вообще отваливаются все методы).
Плюс тонны исключений на каждом шагу. Например, можно написать /**@type {string[]}*/, но нельзя /**@type {{a:string,b:string}[]}*/, он не понимает таких объектов, приходится костылить: /**@type {Array.<{a:string,b:string}>}*/
В случае многомерных массивов всё совсем уж мрачно, а когда дело доходит до интерфейсов и виртуальных функций, тут-то и начинается мат, особенно когда WebStorm из-за этих комментариев начинает путаться, выдавая warning'и на пустом месте, при том что неаннотированный код парсит правильно.
