jsDoc и phpStorm

[cyber]

есть вот такой комментарий

/*
     * Поиск элементов, с соответствующим текстом и отображение результатов
     *
     * @param {string} text текст для поиска.
     * @param {Object} opt_params параметры {optional}.
     * @param {Bool} opt_params.opt_fromBegin задает необходимый текст должен начинаться с начала, или просто быть в текст {optional}.
     * @param {Bool} opt_params.opt_reg задает учет регистра {optional}.
     * @param {Function} opt_params.opt_callback вызываеться когда элементы будут спрятаны.
     *
     * */

function (text, opt_params)

первый параметр обязательный, второй не обязательный объект, с не обязательными свойствами.
Не пойму почему phpStorm отмечает первый параметр как {optional}

[kobezzza]

JSDoc объявляется с

/**

.

PS:
Для передачи литералов логического типа нужно писать

boolean

, а для callback-ов синтаксис function().

@param {function(this:String, number, string): number}
@param {function(new:goog.ui.Menu, string)}

Опциональность параметров показывает знак =

@param {string=}
@param {(number|Object)=}

Также следует помнить об отношении к null:
string, number, boolean, function - не null по умолчанию, можно использовать модификатор ?, например, ?boolean, т.е. boolean|null

Все объекты, например, String, Function могут быть null, а чтобы запретить такое поведение нужно использовать модификатор !, например, !Function

Если примитив задаётся как объект, то название пишется с заглавной буквы,
т.е. для new Boolean нужно писать Boolean, а для true - boolean.

дока
дока 2
дока 3

[cyber]

kobezzza, спасибо

[cyber]

а так описывать если в качестве this, свой класс

@param {function(this:MyClass)}

?

[kobezzza]

@param {function(this:MyClass)}

Да, важно понять, что тип данных - это функция-конструктор или литерал, т.е. то, с чем можно провести instanceof.

НО есть исключение из правил, директива @lends - она используется для декларации литерала объекта как части другого объекта, т.е.

function Foo() {
}

// Тут некоторая функция для создания классов
Class(Foo, /** @lends {Foo.prototype} */ {
    get: function () {}
});

[cyber]

Да, важно понять, что тип данных - это функция-конструктор

я это знаю, просто уточнил.

[cyber]

kobezzza, не могу найти как правильно указать значение по умолчанию ? по ссылкам нашел только для типов по умолчанию..
к примеру, переменная boolean по умолчанию false

[kobezzza]

kobezzza, не могу найти как правильно указать значение по умолчанию ? по ссылкам нашел только для типов по умолчанию..
к примеру, переменная boolean по умолчанию false

Значение по умолчанию можно указывать вместе с названием параметра, например,

@param {string=} [foo='bar']

ну или если ты используешь ECMAScript6, то просто

function foo(foo = 'bar') {
}

WebStorm это поймёт.

[cyber]

kobezzza, thx, и последняя загвоздка на эту тему,
в качестве параметра передается коллекция элементов (полученная через jQuery) правильно ли будет указать тип HTMLCollection ?

[kobezzza]

kobezzza, thx, и последняя загвоздка на эту тему,
в качестве параметра передается коллекция элементов (полученная через jQuery) правильно ли будет указать тип HTMLCollection ?

Нет, т.к.

$('.foo') instanceof jQuery === true

т.е. надо писать jQuery. А вот например для getElementsByTagName будет HTMLCollection.