Pertanyaan Bagaimana mendokumentasikan fungsi anonim (penutupan) dengan jsdoc-toolkit


Saya mencoba mendokumentasikan kode saya menggunakan JSDoc-toolkit. Kode saya dimulai dengan dibungkus dengan fungsi anonim yang mengeksekusi diri sendiri. Bagaimana saya mendokumentasikan ini? Saya telah menghabiskan hampir sepanjang hari untuk ini. JS Docs tidak akan mengenali apa pun di dalam penutupan fungsi anonim karena tidak tahu apa yang harus dilakukan dengan itu. Rusak dan tidak ada komentar saya yang datang.

Kode saya terlihat seperti ini.

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

Terima kasih!


32
2017-11-09 21:24


asal


Jawaban:


Anda dapat menggunakan @namespace dengan @name dan @lends seperti ini:

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

3
2017-11-09 21:58



Anda tidak dapat mendokumentasikan fungsi bertingkat secara langsung. Tetapi Anda dapat melakukan sesuatu seperti ini:

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

Di sini saya pengaturan checkString sebagai pribadi dan batin menjadi deskriptif (karena fungsi bertingkat tidak dapat dijelaskan), Dan kemudian saya meneruskan -p untuk mendokumentasikan fungsi pribadi. Akhirnya, saya menambahkan tautan ke fungsi induk untuk referensi.

kupikir jsdoc tidak perlu rewel dan perlu diganti dengan sesuatu yang lebih baik. Ini adalah pelabuhan javadoc, sehingga memiliki banyak hal yang relevan dengan Java tetapi tidak JS, dan sebaliknya. Ada idiom JS yang sangat umum, seperti penutupan atau fungsi bertingkat, yang sulit atau tidak mungkin untuk didokumentasikan.

Saya selalu memeriksa namepaths saya dan debug menggunakan --explain bendera.


3
2017-12-17 02:11