Как правильно написать jsdoc для кода внутри самовызывающейся функции?

Question

[Ксения]

Подскажите плз, если у меня код внутри самовызывающейся функции, как написать в jsdoc, что самовызывающаяся функция для изоляции пространства имен?

(function() {
let foo = ( msg ) => {
console.log( 'msg' )
};
foo('test');
})();

Answer 1

[Alex Ander]

/**
* @name MyNamespace
* @namespace Hold all functionality
*/
(function () {
    "use strict";
    /** @lends MyNamespace*/
    var stlib = function (param, param, param) { ...All of my code...};
}());

/**
 * @module foobar
 */

/**
* @function
* @author Baa
* @name hello 
* @description Output a greeting
* @param {String} name - The name of the person to say hello
*/
(function hello(name) {
    /**
     * @function
     * @author Baz
     * @inner
     * @private
     * @memberof module:foobar
     * @description Check if the argument is a string (see: {@link module:foobar~hello})
     * @param {String} string - The string
     * @returns {String} Returns true if string is valid, false otherwise
     */ 
    var isString = function checkString(string) { return typeof string === 'string'; };
    if (isString(name))
      console.log('Hello ' + name + '!');
}('Mr. Bubbles'));

Comments

[Ксения]

а если внутри MyNamespace  есть функция, и я к ее описанию добавляю@lends, то весь блок с описанием пропадает из документации

Answer 2

[youngmysteriouslight]

У меня код, написанный по первому варианту Alex Ander, не даёт нужный результат.

Код, который не связывает имена с пространством имён

/**
 * @namespace ZZZ
 */
(function() {
  /** @lends ZZZ */
  
  /**
   * my function.
   */
  function f() {
  }
  
  /**
   * my variable.
   */
  var x = 2;
  
})();

Вот моё предложение:

/**
 * @namespace ZZZ
 */
(/** @lends ZZZ */function() {

  /**
   * my function.
   */
  function f() {
  }
  
  /**
   * my variable.
   */
  var x = 2;
  
})();

Этот код добавляет имена с атрибутом inner (т.е. ZZZ~f, ZZZ~x), причём явное указание static или instance не менияет этого, разве что только явно не указан memberof, как во втором примере Alex Ander.
В целом, lends непосредственно перед функцией function() {} добавляет все имена на верхнем синтаксическом уровне в модуль/класс/неймспейс с атрибутом inner.

Answer 3

[Ксения]

youngmysteriouslight почему-то не работает. Функции внутри самовызывающейся функции в документации видны как глобальные, а в неймспейсе ничего. Вот на чем тренируюсь: https://github.com/2gnc/jslearn/blob/master/reacth...

Если же использовать @ memberof и @ instance, то некорректно выводится описание классов (нет ссылки на родительский класс в описании потомка, не показываются унаследованные методы)

Comments

[youngmysteriouslight]

1. Если Вы хотите, чтобы классы были частью неймспейса, нужно и к ним дописать @ memberof Task03.

2. Учтите, что имена всех сущностей в Вашем примере имеют вид Task1#loop или Task03.Employee. Именно с префиксом, соответствующим неймспейсу.
Поэтому если писать полные имена, будет привязываться и ссылки будут расставляться правильно.

[Ксения]

youngmysteriouslight, ах вот оно что! Спасибо!