javascript - Hvordan beskrive "object"-argumenter i jsdoc?

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

Men hvordan beskriver jeg hvordan parameterobjektet skal struktureres? For eksempel bør det være noe som:

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

Svar #1

Fra @param wiki-siden:

Parametere med egenskaper

Hvis det forventes at en parameter har en bestemt egenskap, kan du dokumentere det umiddelbart etter @param-taggen for den parameteren, slik:

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

Det pleide å være en @config-tag som umiddelbart fulgte den tilsvarende @param, men den ser ut til å ha blitt foreldet (eksempel her).

Svar #2

Per nå finnes det 4 forskjellige måter å dokumentere objekter som parametere/typer på. Hver av dem har sine egne bruksområder. Bare 3 av dem kan imidlertid brukes til å dokumentere returverdier.

For objekter med et kjent sett av egenskaper (Variant A)

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

Denne syntaksen er ideell for objekter som kun brukes som parametere for denne funksjonen og ikke krever ytterligere beskrivelse av hver egenskap. Den kan også brukes for @returns.

For objekter med et kjent sett av egenskaper (Variant B)

Veldig nyttig er syntaksen for parametere med egenskaper:

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

Denne syntaksen er ideell for objekter som kun brukes som parametere for denne funksjonen og som krever ytterligere beskrivelse av hver egenskap. Dette kan ikke brukes for @returns.

For objekter som skal brukes på mer enn ett sted i kilden

I dette tilfellet er en @typedef veldig nyttig. Du kan definere typen på ett sted i koden din og bruke den som en type for @param eller @returns eller andre JSDoc-tagger som kan bruke en type.

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

Du kan deretter bruke dette i en @param-tag:

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

Eller i en @returns:

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

For objekter hvis verdier alle er av samme type

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

Den første typen (string) dokumenterer typen til nøklene som i JavaScript alltid er en string eller i det minste alltid vil bli tvunget til en string. Den andre typen (number) er typen til verdien; dette kan være hvilken som helst type. Denne syntaksen kan også brukes for @returns.

Ressurser

Nyttig informasjon om dokumentasjon av typer kan finnes her:

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

PS:

for å dokumentere en valgfri verdi kan du bruke []:

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

eller :

/**
 * @param {number|undefined} opt_number this number is optional
 */

Svar #3

Jeg ser at det allerede finnes et svar om @return-taggen, men jeg vil gi flere detaljer om den.

Først og fremst gir ikke den offisielle JSDoc 3-dokumentasjonen oss noen eksempler på @return for et tilpasset objekt. Vennligst se https://jsdoc.app/tags-returns.html. Nå, la oss se hva vi kan gjøre inntil en standard dukker opp.

  • Funksjonen returnerer et objekt hvor nøklene genereres dynamisk. Eksempel: {1: 'Pete', 2: 'Mary', 3: 'John'}. Vanligvis itererer vi over dette objektet med hjelp av for(var key in obj){...}.

    Mulig JSDoc i henhold til 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
}

  • Funksjonen returnerer et objekt hvor nøkler er kjente konstanter. Eksempel: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Vi kan enkelt få tilgang til egenskaper i dette objektet: object.id.

    Mulig JSDoc i henhold til https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

    • Lat som.

      /**
 * 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
    }
}

    • Hele Monty.

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

    • Definer en type.

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

    I henhold til https://google.github.io/styleguide/javascriptguide.xml#JsTypes

    • Posttypen.

      /**
 * @return {{myNum: number, myObject}}
 * An anonymous type with the given type members.
 */
function getTmpObject() {
    return {
        myNum: 2,
        myObject: 0 || undefined || {}
    }
}

Svar #4

For @return-taggen bruk {{field1: Number, field2: String}}, se: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

Svar #5

Hvis en parameter forventes å ha en bestemt egenskap, kan du dokumentere den egenskapen ved å legge til en ekstra @param-tagg. For eksempel, hvis en ansatt-parameter forventes å ha navn og avdelingsegenskaper, kan du dokumentere det som følger:

/**
 * 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) {
    // ...
}

Hvis en parameter blir destrukturert uten et eksplisitt navn, kan du gi objektet et passende navn og dokumentere egenskapene det har.

/**
 * 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 }) {
    // ...
};

Kilde: JSDoc

Relaterte artikler