JSDoc для bem-core

Форум /

Наверное все кто используют IDE, а не emacs сталкивались с проблемой, что IDE совсем не понимает BEM блоки. Это все связано с особенностями реализации наследования внутри bem-core - inherit.

При помощи JSDoc я всячески стараюсь объяснить IDE что же такое BEM-block. Но, увы 100% результат пока не достиг, имеются недостатки. Вот пример того как я описываю блоки:

/**
 * @module myBlock
 */
modules.define('myBlock', ['i-bem__dom'], function(provide, BEMDOM) {

/**
 * @augments BEM
 * @bem
 */
var myBlock = BEMDOM.decl(this.name, /** @lends myBlock.prototype */ {
    onSetMod: {
        js: {
            /**
             * @constructs
             */
            inited: function() { /* some code goes here */ }
        }
    }
}, /** @lends myBlock */ {
    live: function() {
        this.liveBindTo('some-elem', 'click', this.prototype._onSomeElemClick);
    }
});

provide(myBlock);

});

Подробнее:

имена классов и модулей не должны содержать тире, хоть BEM и предлагает нам называть блоки через тире, то JSDoc в именах классов тире не понимает, и напроч забивает на весь последующий код.
результат выполнения BEMDOM.decl надо класть в переменную, если сразу положить в provide работать не будет.

В целом данная схема оформления позволяет комфортно работать с прототипной частью блока, что касается live, там я пока не нашел решения.

Я не нашел никакого способа объяснить IDE, что эта часть наследуется от BEMDOM и BEM одновременно, но только от их статической части. Кажется к такому JSDoc не готов. В связи с чем у меня IDE не понимает что this.prototype, это прототип нашего же блока.

Сам я недавно стал заморачиваться с JSDoc и еще многого про него не знаю. Если у вас есть идеи как усовершенствовать описание блоков буду рад любой информации/критике

7 years ago

belozer

/ping

Ребят, есть ли какие-то практики в плане правильного JsDoc в BEM модулях?

в частности интересует как правильно использовать

/** @namespace */ // для группировки: ui, models, api, etc.
/** @event */ // для описания всех событий блока
/** @typedef */ // для описания типов данных

7 years ago

tadatuta

cc @birhoff @blond @zxqfox

7 years ago

qfox

По большей части всё зависит от инструментов, которыми ты в будущем будешь пользоваться. На практике получается, что IDE, равно как и генераторы документации, не расчитаны на то, что твой класс размазан по уровням переопределения, и тогда JSDoc становится несколько ущербным.

Я знаю, что @tenorok сильно упарывался и пытался настроить в WebStorm, но об успехах я не слышал. Мб @birhoff расскажет что у него вышло.

Сам я лет 5 назад перестал смотреть на JSDoc как на средство, которое помогает в рантайме. Максимум, что можно выжать, это статические и динамические проверки типов, авто-генерация документации и может быть какие-то оптимизации при компиляции (типа google closure compiler).

7 years ago

belozer

Да вот благодаря @tenorok'у я сам стал упарываться по ним :)

Чтобы оставлять комментарии, необходимо авторизоваться.