Beste Möglichkeit, anonyme Objekte und Funktionen mit jsdoc zu dokumentieren

Bearbeiten: Dies ist technisch eine zweiteilige Frage. Ich habe die beste Antwort ausgewählt, die die Frage im Allgemeinen abdeckt, und sie mit der Antwort verknüpft, die die spezifische Frage behandelt.

Was ist der beste Weg, um anonyme Objekte und Funktionen mit jsdoc zu dokumentieren?

/**
 * @class {Page} Page Class specification
 */
var Page = function() {

    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     * @param {function} callback Function executed when page is retrieved
     */
    this.getPage = function(pageRequest, callback) {
    }; 
};

Weder das PageRequestObjekt noch das callbackexistieren im Code. Sie werden zur getPage()Laufzeit zur Verfügung gestellt. Aber ich möchte in der Lage sein zu definieren, was das Objekt und die Funktion sind.

Ich kann mit dem Erstellen des PageRequestObjekts davonkommen, um Folgendes zu dokumentieren:

/**
 * @namespace {PageRequest} Object specification
 * @property {String} pageId ID of the page you want.
 * @property {String} pageName Name of the page you want.
 */
var PageRequest = {
    pageId : null,
    pageName : null
};

Und das ist in Ordnung (obwohl ich offen bin für bessere Möglichkeiten, dies zu tun).

Wie kann die callbackFunktion am besten dokumentiert werden? Ich möchte im Dokument darauf hinweisen, dass die Rückruffunktion beispielsweise folgende Form hat:

callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus)

Irgendwelche Ideen, wie das geht?

Mit dem @ name-Tag können Sie Dinge dokumentieren, die im Code nicht vorhanden sind.

/**
 * Description of the function
 * @name IDontReallyExist
 * @function
 * @param {String} someParameter Description
*/

/**
 * The CallAgain method calls the provided function twice
 * @param {IDontReallyExist} func The function to call twice
*/
exports.CallAgain = function(func) { func(); func(); }

Hier ist die Dokumentation zum @ name-Tag . Möglicherweise sind auch Namenspfade hilfreich.

Sie können @callbackoder verwenden @typedef.

/**
 * @callback arrayCallback
 * @param  {object} element - Value of array element
 * @param  {number} index   - Index of array element
 * @param  {Array}  array   - Array itself
 */

/**
 * @param {arrayCallback} callback - function applied against elements
 * @return {Array} with elements transformed by callback
 */
Array.prototype.map = function(callback) { ... }

Um die Antwort von studgeek zu ergänzen, habe ich ein Beispiel bereitgestellt, das zeigt, was Sie mit JsDoc mit Google Closure Compiler tun können.

Beachten Sie, dass die dokumentierten anonymen Typen aus der generierten minimierten Datei entfernt werden und der Compiler sicherstellt, dass gültige Objekte übergeben werden (wenn möglich). Selbst wenn Sie den Compiler nicht verwenden, kann er dem nächsten Entwickler und Tools wie WebStorm (IntelliJ) helfen, ihn zu verstehen und den Code zu vervollständigen.

// This defines an named type that you don't need much besides its name in the code
// Look at the definition of Page#getPage which illustrates defining a type inline
/**  @typedef { pageId : string, pageName : string, contents: string} */
var PageResponse;

/**
 * @class {Page} Page Class specification
 */
var Page = function() {    
    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     *
     * The type for the second parameter for the function below is defined inline
     *
     * @param {function(PageResponse, {statusCode: number, statusMsg: string})} callback
     *        Function executed when page is retrieved
     */
    this.getPage = function(pageRequest, callback) {
    }; 
};

@link kann Inline-Links zu Methoden und Klassen hinzufügen.

/**
 * Get a page from the server
 * @param {PageRequest} pageRequest Info on the page you want to request
 * @param {function} callback Function executed when page is retrieved<br />
 * function({@link PageResponse} pageResponse,{@link PageRequestStatus} pageRequestStatus)
 */
this.getPage = function (pageRequest, callback) {
};

Nicht ideal, aber es erledigt den Job.

Die Google Closure Compiler Anmerkungen haben Typ - Ausdrücke für diese , die die Fähigkeit Typen für bestimmte Argumente , um anzuzeigen , enthalten, Rückgabetyp und auch dies. Viele Bibliotheken versuchen, den Anmerkungen des Google Closure Compiler zu folgen, da sie damit ihren Code verkleinern möchten. Es hat also etwas Schwung. Der Nachteil ist, dass ich keinen Weg sehe, die Beschreibung zu geben.

Für die Bereitstellung der Beschreibung würde möglicherweise der Ansatz JSDoc Toolkit Parameters With Properties funktionieren (siehe unten auf der Seite). Es ist das, was ich gerade mache. Das JSDoc-Toolkit bereitet die Arbeit an V3 vor, sodass das Feedback dort möglicherweise gut ist.

Sie können @see verwenden, um eine Verknüpfung zu einer anderen Methode innerhalb derselben Klasse herzustellen. Die Methode würde niemals verwendet werden, sondern nur zu Dokumentationszwecken.

/**
 * @class {Page} Page Class specification
 */
var Page = function() {

    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     * @param {function} callback Function executed when page is retrieved
     * @see #getPageCallback 
     */
    this.getPage = function (pageRequest, callback) {
    }; 

    /**
     * Called when page request completes 
     * @param {PageResponse} pageResponse The requested page
     * @param {PageRequestStatus} pageRequestStatus Status of the page
     */
    //#ifdef 0
    this.getPageCallback = function (pageResponse, pageRequestStatus) { };
    //#endif 
};

Wenn Sie ein Build-System verwenden, kann die Dummy-Methode leicht im Build weggelassen werden.