Jak dokumentować anonimowe funkcje (zamykanie) za pomocą jsdoc-toolkit

Question

Próbuję udokumentować mój kod przy pomocy JSDoc-toolkit. Mój kod zaczyna się od zapakowania samosprawdzającej anonimowej funkcji. Jak na świecie to dokumentuję? Spędziłem prawie cały dzień na tym. Dokumenty JS nie rozpoznają niczego w zamknięciu anonimowej funkcji, ponieważ nie wiedzą, co z nią zrobić. Przerywa i żaden z moich komentarzy nie przychodzi.

Mój kod wygląda mniej więcej tak.

Dziękujemy!

Answer 1

Można użyć @namespace z @name i @lends tak:

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

Answer 2

nie można udokumentować zagnieżdżone funkcje bezpośrednio. Ale można zrobić coś takiego:

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

Tutaj mam ustawienia checkString jak prywatny i wewnętrzna być opisowe (od Funkcje zagnieżdżone nie można opisać), a potem przechodzą w -p do dokumentować prywatne funkcje. Na koniec dodaję link do funkcji nadrzędnej w celach informacyjnych.

Myślę, że jsdoc jest niepotrzebnie wybredny i musi zostać zastąpiony czymś lepszym. Jest to port javadoc, więc ma wiele rzeczy istotnych dla Javy, ale nie JS i na odwrót. Istnieją bardzo popularne idiagi JS, takie jak zamknięcia lub zagnieżdżonych funkcji, które są trudne lub niemożliwe do udokumentowania.

Zawsze sprawdzam moje tablice i debugowanie przy użyciu flagi --explain.