Как документировать анонимные функции (закрытие) с помощью jsdoc-toolkit - PullRequest
Новая
       26

Как документировать анонимные функции (закрытие) с помощью jsdoc-toolkit

33 голосов
/ 10 ноября 2011

Я пытаюсь документировать свой код с помощью JSDoc-toolkit. Мой код начинается с обертывания самозапускающейся анонимной функции. Как в мире я это документирую? Я провел почти весь день на этом. JS Docs не распознает ничего внутри закрытия анонимной функции, потому что он не знает, что с ним делать. Это ломается, и ни один из моих комментариев не проходит.

Мой код выглядит примерно так. 

/** 
 * @fileoverview BLA BLA BLA
 */

/**
 * This is where I don't know what to put.
 */
 (function () {
     "use strict";

     /** or here */
     var stlib = function (param, param, param) {
         /** or here */
         var share = {
             /** or here */
             config: {
                 button: DOM Element,
                 property: blablabla
             },

             init: function () { ...some init code here}
         };

         share.init();
     };

     widgets.add("share", stlib);
 }());

Спасибо!

Ответы [ 2 ]

3 голосов
/ 17 декабря 2014

Вы не можете документировать вложенные функции напрямую. Но вы можете сделать что-то вроде этого: 

/**
 * @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'));

Здесь я устанавливаю checkString как личное и внутреннее , чтобы оно было описательным (поскольку вложенные функции не могут быть описаны), а затем я передаю -p в документ частных функций. Наконец, я добавляю ссылку на родительскую функцию для справки.

Я думаю, jsdoc излишне привередлив и должен быть заменен чем-то лучшим. Это порт javadoc, поэтому в нем есть много вещей, которые имеют отношение к Java, но не к JS, и наоборот. Есть очень распространенные идиомы JS, такие как замыкания или вложенные функции , которые трудно или невозможно документировать.

Я всегда проверяю свои имена и отлаживаю с помощью флага --explain.

3 голосов
/ 10 ноября 2011

Вы можете использовать @namespace с @name и @lends следующим образом: 

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