Domande sulla documentazione JavaScript: tipi JS

Question

Considerando che lavorerò con un team più grande in futuro, sto cercando di insegnarmi alcuni principi base di annotazione e documentazione per i linguaggi front-end. Attualmente sto lavorando su JS.

Per la maggior parte, sto usando Google's Style Guide come un go-to, ma ho ancora alcune domande.

Diciamo che ho una funzione di ajax in questo modo:

function initFunction(src, wrapper) { 
    $.getJSON(src, { 
    format: "json" 
    }).done(function(data) { 
    var wrapper = $(wrapper), 
     contents = callAnotherFunction($(data)[0]); 

    // Populates the wrapper element. 
    wrapper.append(contents); 

    }).fail(function(jqXHR, textStatus, errorThrown) { 
    alert(textStatus + ": " + errorThrown); 
    }); 
} 

La funzione ha due @param, src e involucro. Ecco alcune domande.

callAnotherFunction(), quindi, accetta come argomento un oggetto e deve restituire un po 'di codice HTML.

1. qual è il tipo di src? Considerando che è JSON, {Object}?
2. qual è il tipo di involucro? Considerando che è un valore come "#myId", String?
3. qual è il tipo di ritorno di questa funzione? È una funzione nulla, ma non so come chiamerei il suo ritorno tipo. Restituisce nulla?
4. qual è il tipo di HTML che è possibile aggiungere a un elemento? È un String?
5. qual è la convenzione JSDoc per la visualizzazione di tutto questo? Qualcosa come questo?

/** * This is a description of this function. It gets a JSON file, uses it as * a jQuery object, and then call another function with the new data. * @param {Object} src JSON file to parse. * @param {String} wrapper HTML element to use as a wrapper for the output. * @return {Null} */

Answer 1

1. Il tipo di argomento non è legato a ciò che rappresenta, ma è il tipo JavaScript dell'argomento. Nel tuo caso src è una stringa che contiene l'url (non importa il recupero dell'URL recupera JSON) quindi il tipo è una stringa. Maggiori informazioni here.
2. Sì, è una stringa.
3. Se la funzione non ha un valore di ritorno, non menzionarla nel JSDoc.
4. Secondo JQuery documentation è:

Tipo: htmlString o elemento o Array o jQuery

elemento DOM, array di elementi, stringa HTML o oggetto jQuery per inserire alla fine di ogni elemento nel set di elementi abbinati.

Quindi dipende da cosa si desidera documentare la propria funzione come accettazione. Se si desidera documentarlo accettando più tipi, si use parentheses and the | character (esempio sotto).

5. Chiudi, ma non si desidera un tipo di reso. Alcune persone mettono anche una riga vuota tra la descrizione e i parametri, ma ciò non è richiesto dal parser.

   /** 
   * This is a description of this function. It gets a JSON file, uses it as 
   * a jQuery object, and then call another function with the new data. 
   * 
   * @param {Object} src  JSON file to parse. 
   * @param {(String|jQuery|DOMElement)} wrapper HTML element to use as a wrapper for the output. 
   */ 
   function initFunction(src, wrapper) { 
   // ... 
   

   In precedenza, abbiamo indicato che wrapper può essere una stringa, oggetto jQuery, o DOMElement.Non siamo entrati nei dettagli di ciò che potrebbe essere un array, né se la stringa è un selettore o un frammento HTML. La descrizione dovrebbe occuparsene. Con molte scelte, potresti dover ricorrere allo {*}.

   Se il parser potrebbe non essere in grado di dire se si tratta di una funzione, devi anche aggiungere il @function tag:

   /** 
   * This is a description of this function. It gets a JSON file, uses it as 
   * a jQuery object, and then call another function with the new data. 
   * 
   * @function 
   * 
   * @param {Object} src  JSON file to parse. 
   * @param {(String|jQuery|DOMElement)} wrapper HTML element to use as a wrapper for the output. 
   */ 
   var initFunction = function(src, wrapper) { 
   // ... 
   

   a seconda del contesto, si può preferire @method-@function (sono sinonimi) .

Answer 2

Come già detto Emanuele, il primo argomento può essere solo una stringa, che rappresenta un URL.

Tuttavia, il secondo parametro (wrapper) potrebbe essere uno string o uno DOM element. Non solo una stringa.

Non so come si potrebbe istruire JSDoc che la variabile potrebbe essere di due tipi diversi però.

Answer 3

Per prima cosa è necessario utilizzare il file jQuery JSDoc extern.
Annota le funzioni di conseguenza, le funzioni sono annotate in questo modo perché del file extern jQuery.

/** 
* @param {!string} src 
* @param {(jQuerySelector|Element|Object|Array<Element>|jQuery|string|function())=} wrapper 
*/ 
function initFunction(src, wrapper) { 
    $.getJSON(src, { 
     format: "json" 
    }).done(function(data) { 
     var wrapper = $(wrapper), 
      contents = callAnotherFunction($(data)[0]); 

     // Populates the wrapper element. 
     wrapper.append(contents); 

    }).fail(function(jqXHR, textStatus, errorThrown) { 
     alert(textStatus + ": " + errorThrown); 
    }); 
} 

/** 
* @param {!Object} obj 
* @return {(string|Element|Array<Element>|jQuery|function(number,string))} 
*/ 
function callAnotherFunction(obj) { 
    . 
    . 
    . 
} 

Answer 4

La funzione di documentazione minima che al solito faccio è:

/** 
Purpose: state the purpose of the function 
parameters: 
    src: string, required: the url to the api service. [paramName: type, option: purpose. 
{list individual parameters} 
Assumption: describe any dependencies. Any callback, etc. 
Return: string, json format. 
*/ 
function foo(src, param) {} 

mettersi nei panni di qualcuno. Che cosa è necessario sapere rapidamente prima di tentare di apportare modifiche al codice di qualcuno.