Bagaimana cara menggambarkan argumen "objek" di jsdoc?

316
// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}

Tetapi bagaimana saya menggambarkan bagaimana objek parameter harus disusun? Contohnya harus seperti:

{
  setting1 : 123, // (required, integer)
  setting2 : 'asdf' // (optional, string)
}
Andy Hin
sumber

Jawaban:

428

Dari halaman wiki @param :


Parameter Dengan Properti

Jika suatu parameter diharapkan memiliki properti tertentu, Anda dapat mendokumentasikannya segera setelah tag @param untuk parameter itu, seperti:

 /**
  * @param userInfo Information about the user.
  * @param userInfo.name The name of the user.
  * @param userInfo.email The email of the user.
  */
 function logIn(userInfo) {
        doLogIn(userInfo.name, userInfo.email);
 }

Dulu ada tag @config yang segera mengikuti @param yang sesuai, tetapi tampaknya sudah usang ( contoh di sini ).

Jonny Buchanan
sumber
17
sayangnya tag pengembalian tampaknya tidak memiliki setara code.google.com/p/jsdoc-toolkit/wiki/TagReturns
Michael Bylstra
1
Dalam jawaban yang serupa ini stackoverflow.com/a/14820610/3094399 mereka juga menambahkan opsi @param {Object} di awal. Kira itu mungkin berlebihan.
pcatre
Apakah Anda memiliki contoh dengan parameter destruksi ES6? Dalam kasus saya, saya tidak memiliki actionnama, saya menulis `foo = ({arg1, arg2, arg2}) => {...}`. Sunting: pertanyaan di sini stackoverflow.com/questions/36916790/…
Eric Burel
tahu bagaimana mendokumentasikan objek anggota yang merupakan opsi? Maksud saya objek pengguna saya harus memiliki nama pengguna, dan dapat memiliki nama lengkap. jadi bagaimana saya menentukan nama lengkap itu opsional
Yash Kumar Verma
167

Sekarang ada 4 cara berbeda untuk mendokumentasikan objek sebagai parameter / tipe. Masing-masing memiliki kegunaan sendiri. Hanya 3 dari mereka yang dapat digunakan untuk mendokumentasikan nilai pengembalian.

Untuk objek dengan set properti yang dikenal (Varian A)

/**
 * @param {{a: number, b: string, c}} myObj description
 */

Sintaks ini sangat ideal untuk objek yang hanya digunakan sebagai parameter untuk fungsi ini dan tidak memerlukan deskripsi lebih lanjut dari setiap properti. Dapat digunakan untuk @returnsjuga .

Untuk objek dengan set properti yang dikenal (Varian B)

Sangat berguna adalah parameter dengan sintaksis properti :

/**
 * @param {Object} myObj description
 * @param {number} myObj.a description
 * @param {string} myObj.b description
 * @param {} myObj.c description
 */

Sintaks ini sangat ideal untuk objek yang hanya digunakan sebagai parameter untuk fungsi ini dan yang memerlukan deskripsi lebih lanjut dari setiap properti. Ini tidak dapat digunakan untuk @returns.

Untuk objek yang akan digunakan di lebih dari satu titik dalam sumber

Dalam hal ini @typedef sangat berguna. Anda dapat menentukan jenis pada satu titik di sumber Anda dan menggunakannya sebagai jenis untuk @paramatau @returnsatau tag JSDoc lainnya yang dapat menggunakan suatu jenis.

/**
 * @typedef {Object} Person
 * @property {string} name how the person is called
 * @property {number} age how many years the person lived
 */

Anda kemudian dapat menggunakan ini dalam @paramtag:

/**
 * @param {Person} p - Description of p
 */

Atau dalam @returns:

/**
 * @returns {Person} Description
 */

Untuk objek yang nilainya semua jenis yang sama

/**
 * @param {Object.<string, number>} dict
 */

Jenis pertama (string) mendokumentasikan jenis kunci yang dalam JavaScript selalu berupa string atau setidaknya akan selalu dipaksa ke string. Tipe kedua (angka) adalah tipe nilai; ini bisa berupa tipe apa saja. Sintaks ini dapat digunakan untuk @returnsjuga.

Sumber daya

Informasi yang berguna tentang tipe-tipe dokumentasi dapat ditemukan di sini:

https://jsdoc.app/tags-type.html

PS:

untuk mendokumentasikan nilai opsional yang dapat Anda gunakan []:

/**
 * @param {number} [opt_number] this number is optional
 */

atau:

/**
 * @param {number|undefined} opt_number this number is optional
 */
Simon Zyx
sumber
Apakah varian 1 berfungsi dengan beberapa jenis properti? Suka {{dir: A|B|C }}?
CMCDragonkai
Anotasi jenis apa pun harus dimungkinkan di sini, jadi ya
Simon Zyx
Dan untuk objek yang kuncinya dihasilkan secara dinamis? Seperti{[myVariable]: string}
Frondor
135

Saya melihat bahwa sudah ada jawaban tentang tag @return, tetapi saya ingin memberikan rincian lebih lanjut tentang hal itu.

Pertama-tama, dokumentasi JSDoc 3 resmi tidak memberikan contoh tentang @return untuk objek kustom. Silakan lihat https://jsdoc.app/tags-returns.html . Sekarang, mari kita lihat apa yang bisa kita lakukan sampai beberapa standar muncul.

  • Fungsi mengembalikan objek tempat kunci dihasilkan secara dinamis. Contoh: {1: 'Pete', 2: 'Mary', 3: 'John'}. Biasanya, kami mengulangi objek ini dengan bantuan for(var key in obj){...}.

    Kemungkinan JSDoc menurut https://google.github.io/styleguide/javascriptguide.xml#JsTypes

    /**
     * @return {Object.<number, string>}
     */
    function getTmpObject() {
        var result = {}
        for (var i = 10; i >= 0; i--) {
            result[i * 3] = 'someValue' + i;
        }
        return result
    }
  • Fungsi mengembalikan objek di mana kunci dikenal konstanta. Contoh: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Kita dapat dengan mudah mengakses properti dari objek ini: object.id.

    Kemungkinan JSDoc menurut https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

    • Berpura-pura.

      /**
       * Generate a point.
       *
       * @returns {Object} point - The point generated by the factory.
       * @returns {number} point.x - The x coordinate.
       * @returns {number} point.y - The y coordinate.
       */
      var pointFactory = function (x, y) {
          return {
              x:x,
              y:y
          }
      }
    • Monty Penuh.

      /**
       @class generatedPoint
       @private
       @type {Object}
       @property {number} x The x coordinate.
       @property {number} y The y coordinate.
       */
      function generatedPoint(x, y) {
          return {
              x:x,
              y:y
          };
      }
      
      /**
       * Generate a point.
       *
       * @returns {generatedPoint} The point generated by the factory.
       */
      
      var pointFactory = function (x, y) {
          return new generatedPoint(x, y);
      }
    • Tentukan tipe.

      /**
       @typedef generatedPoint
       @type {Object}
       @property {number} x The x coordinate.
       @property {number} y The y coordinate.
       */
      
      
      /**
       * Generate a point.
       *
       * @returns {generatedPoint} The point generated by the factory.
       */
      
      var pointFactory = function (x, y) {
          return {
              x:x,
              y:y
          }
      }

    Menurut https://google.github.io/styleguide/javascriptguide.xml#JsTypes

    • Jenis rekaman.

      /**
       * @return {{myNum: number, myObject}}
       * An anonymous type with the given type members.
       */
      function getTmpObject() {
          return {
              myNum: 2,
              myObject: 0 || undefined || {}
          }
      }
vogdb
sumber
Adakah yang tahu cara menghasilkan ini di IntelliJ / Webstorm? Secara khusus saya berbicara tentang opsi ketiga - menentukan jenis.
Erez Cohen
Tolong jelaskan. Apakah Anda ingin memiliki beberapa tombol pintas atau pintasan dalam IDE untuk menghasilkan dokumen tersebut atau apakah Anda ingin IDE memahami dokumen tersebut? Mungkin keduanya?
vogdb
@vogdb, bisakah Anda melihat masalah ini? Saya yakin case use ini tidak tercakup dengan contoh hebat Anda: stackoverflow.com/questions/53191739/…
Pavel Polyakov
@PavelPolyakov saya sudah melihat. Saya benar-benar tidak tahu bagaimana menjawab pertanyaan Anda. Saya keluar dari JS untuk sementara waktu. Jangan ragu untuk mengedit jawaban saya jika Anda memiliki info baru.
vogdb
2

Jika suatu parameter diharapkan memiliki properti tertentu, Anda dapat mendokumentasikan properti itu dengan memberikan tag @param tambahan. Misalnya, jika parameter karyawan diharapkan memiliki nama dan properti departemen, Anda dapat mendokumentasikannya sebagai berikut:

/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
function(employees) {
    // ...
}

Jika parameter dirusak tanpa nama eksplisit, Anda bisa memberikan objek yang sesuai dan mendokumentasikan propertinya.

/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

Sumber: JSDoc

Karma Blackshaw
sumber
0

Ada @configtag baru untuk kasus ini. Mereka terhubung ke sebelumnya @param.

/** My function does X and Y.
    @params {object} parameters An object containing the parameters
    @config {integer} setting1 A required setting.
    @config {string} [setting2] An optional setting.
    @params {MyClass~FuncCallback} callback The callback function
*/
function(parameters, callback) {
    // ...
};

/**
 * This callback is displayed as part of the MyClass class.
 * @callback MyClass~FuncCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */
Mike DeSimone
sumber
1
Bisakah Anda mengarahkan ke dokumentasi untuk @configtag? Saya tidak menemukan apa pun di usejsdoc.org , dan halaman ini menunjukkan @configtelah usang.
Dan Dascalescu
4
Saya pikir @configsudah usang pada saat ini. YUIDoc merekomendasikan penggunaannya @attributesebagai gantinya.
Mike DeSimone