Javascript-форум (https://javascript.ru/forum/)
-   Оффтопик (https://javascript.ru/forum/offtopic/)
-   -   jsDoc и phpStorm (https://javascript.ru/forum/offtopic/46827-jsdoc-i-phpstorm.html)

cyber 25.04.2014 17:26

jsDoc и phpStorm
 
есть вот такой комментарий
/*
     * Поиск элементов, с соответствующим текстом и отображение результатов
     *
     * @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 25.04.2014 18:01

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 25.04.2014 19:49

kobezzza, спасибо

cyber 25.04.2014 20:06

а так описывать если в качестве this, свой класс
@param {function(this:MyClass)}

?

kobezzza 25.04.2014 20:59

Цитата:

Сообщение от cyber (Сообщение 309278)
а так описывать если в качестве this, свой класс
@param {function(this:MyClass)}

?

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

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

function Foo() {
}

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

cyber 25.04.2014 21:08

Цитата:

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

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

cyber 25.04.2014 21:12

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

kobezzza 25.04.2014 21:23

Цитата:

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

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

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


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

function foo(foo = 'bar') {
}


WebStorm это поймёт.

cyber 25.04.2014 21:27

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

kobezzza 25.04.2014 21:33

Цитата:

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

Нет, т.к.

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


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


Часовой пояс GMT +3, время: 16:31.