Was ist der richtige Weg, um einen jQuery-Parametertyp mit JSDoc zu dokumentieren?

Lesezeit: 2 Minuten

Benutzeravatar von Jean-Philippe Martin
Jean-Philippe Martin

Ich versuche, mein Programm mit der JSDoc-Syntax für mich und die Leute zu dokumentieren, die sich meinen Code ansehen müssen. Ich versuche auch, meine Fähigkeiten zu verbessern.

Bei einem Parameter vom Typ jQuery bin ich etwas ratlos. Ich weiß, dass das ein Objekt ist, aber es kommt in meinem Programm ziemlich häufig vor, also denke ich, ich sollte zuerst eine Typedef für den jQuery-Typ deklarieren und sie dann als meinen Parametertyp verwenden. Also frage ich, wäre es der richtige Weg, es zu tun?

/**
 * DOM object referenced by jQuery
 * @typedef {jQuery} $jQueryDomObject
 */

/**
* SOAP call that does ...
*
* @param {string} code Some desc ...
* @param {callback} fnctVa Some desc ...
* @param {$jQueryDomObject} $attrib Input field that ...
*/
myfunction = function (code, fnctVa, $attrib) {};

Ich habe auch auf SO diese Frage gefunden, etwas ähnlich:
Wie kann ich JSDoc dazu bringen, meinen Parameter als jQuery-Objekt zu markieren?

  • Das Richtige ist, keinen SOAP-Aufruf mit einem jQ-Objekt zu tätigen und Bedenken zu trennen. Sag nur. Trotzdem interessante Frage.

    – Benjamin Grünbaum

    27. November 2013 um 20:20 Uhr


  • Ok ich probier das mal aus. Würden Sie stattdessen ein Muster vorschlagen?

    – Jean-Philippe Martin

    27. November 2013 um 20:23 Uhr

  • Die Trennung von Interessen ist ein Prinzip und kein Muster. Die Idee in diesem Fall (es gilt für mehr als GUI) ist, dass Ihre Präsentationslogik und Ihre Geschäftslogik nicht so gemischt werden sollten. Einige gängige Entwurfsmuster, die sich mit diesem Problem befassen, sind Mediator, Observer und Event Emitter. Einige Architekturmuster, die das Problem angehen, sind MVC, MVVM und MVP.

    – Benjamin Grünbaum

    27. November 2013 um 20:33 Uhr

  • Danke für den Architekturtipp … ok, die GUI spricht also nicht direkt mit den Daten und umgekehrt. Ich habs.

    – Jean-Philippe Martin

    27. November 2013 um 20:36 Uhr

  • @Jean-PhilippeMartin, ich habe so ziemlich den gleichen Legacy-Code dokumentiert, den ich nicht geschrieben habe.

    – Andy

    27. November 2013 um 20:49 Uhr

Für einen Parameter, der ein jQuery-Objekt ist, mache ich oft nur:

@param {jQuery} foo

Und definieren Sie nicht weiter, was jQuery ist. Es ist hinlänglich bekannt. Wenn Sie möchten, können Sie dies jedoch mit jsdoc 3 tun:

/**
 * jQuery object
 * @external jQuery
 * @see {@link http://api.jquery.com/jQuery/}
 */

/**
 * SOAP call that does ...
 *
 * @param {string} code Some desc ...
 * @param {callback} fnctVa Some desc ...
 * @param {external:jQuery} $attrib Input field that ...
 */
var myfunction = function (code, fnctVa, $attrib) {};

Benutzeravatar von Jean-Philippe Martin
Jean-Philippe Martin

Ich sah auch weiter github/js3doc:

@param {jQuery object} obj The jQuery object you're looking for.

oder github/js3doc

@param {module:jquery} jquery Some desc...

1435690cookie-checkWas ist der richtige Weg, um einen jQuery-Parametertyp mit JSDoc zu dokumentieren?

This website is using cookies to improve the user-friendliness. You agree by using the website further.

Privacy policy