Jak opisać argumenty „obiektowe” w 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) {
}

Ale jak opisać strukturę obiektów parametrów? Na przykład powinno to być coś takiego:

{
  setting1 : 123, // (required, integer)
  setting2 : 'asdf' // (optional, string)
}
Andy Hin
źródło

Odpowiedzi:

428

Ze strony wiki @param :


Parametry z właściwościami

Jeśli oczekuje się, że parametr będzie miał określoną właściwość, możesz udokumentować go bezpośrednio po znaczniku @param dla tego parametru, na przykład:

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

Kiedyś był tag @config, który bezpośrednio następował po odpowiednim @paramie, ale wygląda na to, że jest przestarzały ( przykład tutaj ).

Jonny Buchanan
źródło
17
niestety, wydaje się, że tag
return
1
W tej podobnej odpowiedzi stackoverflow.com/a/14820610/3094399 na początku dodali także opcje @param {Object}. Ale może to być zbędne.
pcatre
Czy masz jakiś przykład parametrów niszczenia ES6? W moim przypadku nie mam actionnazwy, piszę `foo = ({arg1, arg2, arg2}) => {...}`. Edycja: pytanie tutaj stackoverflow.com/questions/36916790/...
Eric Burel
jakiś pomysł, jak udokumentować element członkowski, który jest opcją? Mam na myśli, że mój obiekt użytkownika powinien mieć nazwę użytkownika i może mieć pełną nazwę. więc jak określić, że pełna nazwa jest opcjonalna
Yash Kumar Verma
167

Do tej pory istnieją 4 różne sposoby dokumentowania obiektów jako parametrów / typów. Każdy ma swoje własne zastosowania. Jednak tylko 3 z nich mogą być użyte do udokumentowania wartości zwracanych.

Dla obiektów o znanym zestawie właściwości (wariant A)

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

Ta składnia jest idealna dla obiektów, które są używane tylko jako parametry dla tej funkcji i nie wymagają dalszego opisu każdej właściwości. To może być stosowany do @returnstak dobrze .

Dla obiektów o znanym zestawie właściwości (wariant B)

Bardzo przydatne są parametry ze składnią właściwości :

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

Ta składnia jest idealna dla obiektów, które są używane tylko jako parametry dla tej funkcji i które wymagają dalszego opisu każdej właściwości. Nie można tego użyć @returns.

Dla obiektów, które będą używane w więcej niż jednym punkcie źródłowym

W tym przypadku @typedef jest bardzo przydatny. Można zdefiniować typ w jednym punkcie w źródle i użyć go jako typ dla @paramlub @returnslub innych znaczników JSDoc, które mogą skorzystać z typu.

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

Następnie możesz użyć tego w @paramtagu:

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

Lub w @returns:

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

Dla obiektów, których wartości są tego samego typu

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

Pierwszy typ (ciąg znaków) dokumentuje rodzaj kluczy, które w JavaScript zawsze są ciągiem lub przynajmniej zawsze będą wymuszone na ciąg. Drugi typ (liczba) to rodzaj wartości; może to być dowolny typ. Tej składni można również użyć @returns.

Zasoby

Przydatne informacje na temat typów dokumentacji można znaleźć tutaj:

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

PS:

aby udokumentować wartość opcjonalną, możesz użyć []:

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

lub:

/**
 * @param {number|undefined} opt_number this number is optional
 */
Simon Zyx
źródło
Czy wariant 1 działa z wieloma typami właściwości? Jak {{dir: A|B|C }}?
CMCDragonkai
Wszelkie adnotacje typu powinny być tutaj możliwe, więc tak
Simon Zyx
A dla obiektów, których klucze są generowane dynamicznie? Jak{[myVariable]: string}
Frondor,
135

Widzę, że już istnieje odpowiedź na temat tagu @return, ale chcę podać więcej szczegółów na ten temat.

Po pierwsze, oficjalna dokumentacja JSDoc 3 nie podaje żadnych przykładów dotyczących @return dla obiektu niestandardowego. Proszę zobaczyć https://jsdoc.app/tags-returns.html . Zobaczmy teraz, co możemy zrobić, aż pojawi się jakiś standard.

  • Funkcja zwraca obiekt, w którym klucze są generowane dynamicznie. Przykład: {1: 'Pete', 2: 'Mary', 3: 'John'}. Zwykle iterujemy ten obiekt za pomocąfor(var key in obj){...} .

    Możliwy JSDoc zgodnie z 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
    }
  • Funkcja zwraca obiekt, w którym klucze są znanymi stałymi. Przykład: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Możemy łatwo uzyskać dostęp do właściwości tego obiektu object.id.

    Możliwy JSDoc według https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

    • Sfałszuj to.

      /**
       * 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
          }
      }
    • The Full 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);
      }
    • Zdefiniuj typ.

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

    Według https://google.github.io/styleguide/javascriptguide.xml#JsTypes

    • Rodzaj rekordu.

      /**
       * @return {{myNum: number, myObject}}
       * An anonymous type with the given type members.
       */
      function getTmpObject() {
          return {
              myNum: 2,
              myObject: 0 || undefined || {}
          }
      }
vogdb
źródło
Czy ktoś zna sposób na wygenerowanie tego w IntelliJ / Webstorm? Mówię konkretnie o trzeciej opcji - zdefiniuj typ.
Erez Cohen
Proszę opracować. Czy chcesz mieć skrót klawiszowy lub skrót do IDE, aby wygenerować te docu, czy też chcesz, aby twoje IDE je rozumiało? Może obydwa?
vogdb
@vogdb, czy mógłbyś spojrzeć na ten problem? Uważam, że ten przypadek użycia nie jest objęty twoimi świetnymi przykładami: stackoverflow.com/questions/53191739/...
Pavel Polyakov
@PavelPolyakov Szukałem. Naprawdę nie wiem jak odpowiedzieć na twoje pytanie. Przez jakiś czas jestem poza JS. Jeśli masz jakieś nowe informacje, edytuj moją odpowiedź.
vogdb
2

Jeśli oczekuje się, że parametr będzie miał określoną właściwość, możesz ją udokumentować, podając dodatkowy tag @param. Na przykład jeśli oczekuje się, że parametr pracownika będzie miał właściwości nazwy i działu, można go udokumentować w następujący sposób:

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

Jeśli parametr zostanie zniszczony bez wyraźnej nazwy, możesz nadać obiektowi odpowiedni i udokumentować jego właściwości.

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

Źródło: JSDoc

Karma Blackshaw
źródło
0

W @configtych przypadkach jest nowy tag. Odnoszą się do poprzednich @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
źródło
1
Czy możesz wskazać dokumentację @configznacznika? Nic nie znalazłem na usejsdoc.org , a ta strona sugeruje, @configże jest przestarzała.
Dan Dascalescu
4
Myślę, że @configw tym momencie jest przestarzały. YUIDoc zaleca używanie @attributezamiast tego.
Mike DeSimone