Gibt es eine Möglichkeit zu vermeiden, mit der JSDoc "@method" Annotation

Question

Ich bin kein großer Fan von generierten Dokumentation persönlich (ich bin eher ein "Lesen Sie die Quelle Luke" ein bisschen Kerl), aber ich kann sehen, wie Eine solche Dokumentation könnte für andere nützlich sein. Nun, normalerweise würde ihre Erstellung von Dokumentation mich nicht beeinflussen, außer einer Sache: @method.

meisten JSDoc Anmerkungen (zB @param.) Sind noch jemand perfekt nützlich, um die Quelle zu lesen, aber @method ist zu 100% redundant:

/* 
* @param num number to add five to 
* @method addFive 
*/ 
function addFive(num) { ... 

Also, würde ich wirklich zu vermeiden, wie Hunderte von @method Leitungen unseren Code überladen. Mein Mitarbeiter glaubt jedoch, dass @method für die JSDoc-Generatoren notwendig ist (er verwendet den YUI-Generator), um die Methodenlisten der Klassen generieren zu können.

Also meine Frage (an die JSDoc Experten da draußen) ist: Gibt es eine Möglichkeit, nützliche Dokumentation (dh mit den Methoden einer Klasse aufgeführt) ohne @method zu generieren? Oder wenn @method wirklich benötigt wird, gibt es einen JSDoc-Generator, der den Methodennamen von dem Funktionsnamen ableiten kann, so dass ich mit @method anstelle von @method addFive davonkommen kann?

P.S. Wenn es eine Antwort "du machst es falsch" gibt, die die Frage nicht direkt beantwortet, sondern eine Möglichkeit vorschlägt, das Problem vollständig zu vermeiden, würde ich es gerne hören. Ich bin sicherlich kein JSDoc-Experte.

Answer 1

Ihr Mitarbeiter ist nicht streng korrekt.

Die @method ist eine Erweiterung, die ein Synonym für @function ist, die defined here ist.

In dieser Dokumentation müssen Sie nur @function bis force JSDoc verwenden, um eine Variable als eine Funktion zu erkennen. Ein Beispiel hierfür wäre:

/** 
* @function 
*/ 
var func = functionGenerator.generate(); 

Von einem Objekt Perspektive, die Sie das gleiche tun wollen würden, wenn Sie ein Function-Objekt zu einem Objekt Element in einer nicht-offensichtlichen Art und Weise (durch ‚nicht offensichtlich‘ zuweisen , Ich meine in Bezug auf statische Analyse, dh wenn Sie keinen Funktionsausdruck verwenden).

Also, so etwas wie

var ageGetter = function() { 
    console.log("A lady never tells"); 
} 

var Person = { 

    name: "Gertrude", 

    getAge: ageGetter 

    getName: function() { 
    return this.name; 
    } 
} 

Würde die explizite Verwendung von @method oder @function für getAge, erfordern aber nicht für getName.

Endgültiger Punkt: Sie müssen den Namen @method nicht explizit einschließen, es sei denn, das ist auch nicht ableitbar (an diesem Punkt tun Sie wahrscheinlich eine ziemlich funky Instanziierung, also wahrscheinlich nicht in der Lage gewesen, sich zu verlassen auf Auto-Doc-Generation sowieso viel).

Answer 2

Ich könnte hier falsch liegen, aber wegen der Vielzahl von Möglichkeiten, Dinge in JavaScript zu definieren, benötigen Sie Art @method für bestimmte Definitionen.

// JSDoc will recognize this as an object member 
var obj = { 
    mymethod: function() {} 
}; 

// There is no way for JSDoc to tell where my method is going to end up 
var mymethod = function() {}; 
obj.mymethod = mymethod;