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.

cyber 25.04.2014 21:38

Цитата:

Сообщение от kobezzza
$('.foo') instanceof jQuery === true

я понял к чему ты, @param {jQuery}

cyber 10.05.2014 17:24

как правильно описать в jsDoc, что внутри возвращаемого массива объекты

@return { Array }

и как еще правильно описать , что внутри возвращаемого массива, объекты или Element (при условие что в качестве параметра переданно true)

Octane 10.05.2014 17:27

@returns {Array.<Object>}

@returns {Array.<(Object|HTMLElement)>}

cyber 10.05.2014 17:33

Цитата:

Сообщение от Octane
@returns {Array.<(Object|HTMLElement)>}

спасибо, но я не совсем правильно написал,
Цитата:

Сообщение от cyber
, что внутри возвращаемого массива, объекты или Element

нужно описать что возвращает массив с вложенными объектами или объект с вложеными массива, на сколько я понял так:
@return { Array.<Object> | Object.<Array> }

Octane 10.05.2014 17:40

тут http://usejsdoc.org/tags-type.html везде круглые скобки еще ставят, при перечислении типов

cyber 10.05.2014 17:46

Octane, thx


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