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

Question

Edit: Dies ist technisch eine 2-teilige Frage. Ich habe die beste Antwort gewählt, die die Frage im Allgemeinen behandelt und 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 die PageRequest Objekt oder die callback existieren im Code. Sie werden zur Laufzeit an getPage() übergeben. Aber ich möchte gerne definieren können, was das Objekt und die Funktion sind.

Ich kann mit der Erstellung der PageRequest Objekt weg, das 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 auf bessere Möglichkeiten offen bin, dies zu tun).

Was ist der beste Weg, um die callback Funktion zu dokumentieren? Ich möchte es in dem Dokument machen weiß, dass zum Beispiel der Callback-Funktion in Form ist:

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

Irgendwelche Ideen, wie dies zu tun?

Answer 1

können Sie Sachen dokumentieren, die im Code existieren tut durch die @name-Tag:

 /** 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 die @name tag documentation ist. Sie könnten auch name paths nützlich finden.

Answer 2

Sie können @see verwenden, um eine Verbindung zu einer anderen Methode innerhalb derselben Klasse herzustellen. Die Methode würde niemals verwendet werden, sie wäre nur zu Dokumentationszwecken da.

Wenn Sie eine Art von Build-System verwenden, könnte die Dummy-Methode einfach aus dem Build weggelassen werden.

Answer 3

@link können 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 macht die Arbeit erledigt.

Answer 4

Die Google Closure Compiler Anmerkungen hat Type Expressions für diese, die die Möglichkeit enthält, Typ für bestimmte Argumente, Rückgabetyp und sogar dies anzugeben. Viele Bibliotheken betrachten die Google Closure-Compiler-Annotationen, weil sie damit ihren Code verkleinern möchten. Es hat also etwas Schwung. Der Nachteil ist, ich sehe keinen Weg, die Beschreibung zu geben.

Für die Beschreibung vielleicht die JSDoc Toolkit Parameters With Properties Ansatz würde funktionieren (siehe unten auf der Seite). Genau das mache ich gerade. Das JSDoc-Toolkit bereitet auf die Arbeit an V3 vor, so dass das Feedback gut sein kann.

Answer 5

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

Beachten Sie, dass die dokumentierten anonymen Typen aus der generierten minimierten Datei entfernt werden und der Compiler dafür sorgt, dass gültige Objekte (wenn möglich) übergeben werden.Auch wenn Sie den Compiler nicht verwenden, kann er dem nächsten Entwickler und den Tools wie WebStorm (IntelliJ) helfen, ihn zu verstehen und Ihnen Code-Vervollständigung zu geben.

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

Answer 6

können Sie @callback oder @typedef verwenden.

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