JSDoc @param wraz z @deprecated

Mam funkcję JavaScript pobieranie niektórych parametrów, w tym typów obiektów. Jednak jedna właściwość parametru, który jest obiektem, zostanie użyta jako przestarzała. Chciałbym wskazać tę sytuację w dokumentacji, jednak nie wiem, jak używać tagu @param z @deprecated. Rozważmy przykład poniżej:JSDoc @param wraz z @deprecated

/** 
* 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 
}

Chcę wycofać właściwość "type" obiektu "options". Jak mogę to zrobić, czy mogę?

Źródło

2015-04-21 mhmtztmr

Zamierzam poprzedzić opis parametru za pomocą wyrażenia "ODRADZANE:". Potem coś 'console.log' zrobi, jeśli użytkownik go dotknie. – Droogans

Nie można wycofać parametrów ani właściwości, ale należy oznaczyć @param jako opcjonalny, taki jak ten '@param {string =} ' – cgTag

@ Droogany, oczywiście, możliwe jest poinformowanie użytkownika o nieaktualnych parametrach w jakikolwiek sposób. Zastanawiam się tylko, czy istnieje zestandaryzowany sposób. – mhmtztmr

Official JSDoc documentation nie oznacza, że znacznik @deprecated może zostać użyty do wycofania czegoś innego niż cały symbol.

Znacznik @deprecated może służyć do dokumentowania, że np. Funkcja jako całość została uznana za przestarzałą.

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

}

Można oczywiście, jak @Droogans powiedział w komentarzach, dodać coś takiego deprecated: przed opisem @param. Jeśli programista w jakiś sposób kończy korzystanie z nieaktualnej funkcji, możesz zaimplementować jakieś ostrzeżenie.

Źródło

2017-02-25 15:27:21

Odpowiedz

Powiązane problemy