JSDoc @param zusammen mit @deprecated

Question

Ich habe eine JavaScript-Funktion erhalten einige Parameter einschließlich Objekttypen. Eine Eigenschaft eines Parameters, die ein Objekt ist, wird jedoch als veraltet verwendet. Ich möchte diese Situation in der Dokumentation angeben, aber ich weiß nicht, wie @param-Tag mit @deprecated verwendet wird. Betrachten Sie das Beispiel unten:

/** 
* This function does something. 
* 
* @name myFunction 
* @function 
* @since 3.0 
* @param {function} [onSuccess] success callback 
* @param {function} [onFailure] failure callback 
* @param {object} [options] options for function 
* @param {string} [options.lang] display language 
* @param {string} [options.type] type of sth 
*/ 

this.myFunction= function (onSuccess, onFailure, options) { 
    //do something 
} 

Ich möchte "Typ" -Eigenschaft von "Optionen" -Objekt veralten. Wie kann ich das machen oder kann ich?

Answer 1

Official JSDoc documentation bedeutet nicht, dass das @deprecated-Tag verwendet werden kann, um etwas anderes als ein ganzes Symbol abzulehnen.

Das Tag kann verwendet werden, um zu dokumentieren, dass zum Beispiel eine Funktion als Ganzes veraltet ist.

/** 
* @deprecated since version 2.0.0 
*/ 
function old() { 

} 

Sie können natürlich, wie @Droogans in den Kommentaren gesagt, so etwas wie deprecated: vor der @param Beschreibung hinzuzufügen. Wenn ein Entwickler die veraltete Funktion immer noch verwendet, könnten Sie eine Art von Warnung implementieren.

/** 
* @param {string=} bar - Deprecated: description 
*/ 
function foo (bar) { 
    if (bar) { 
    console.warn('Parameter bar has been deprecated since 2.0.0') 
    } 
}