Documenta la funzione che assume parametri casuali?

Question

Documenta la funzione che assume parametri casuali?

#1 da (5 voti)

1

Qual è l'approccio migliore per la creazione di documentazione (visualizzazione del prototipo di funzione se lo si desidera) per le funzioni che assumono una varietà di forme diverse in termini di parametri.

Diciamo che ci sono 10 scelte diverse:

param(name);
param(name, type);
param(name, options);
param(name, type, options);
param(name, fn);
param(name, type, fn);
param(name, options, fn);
param(name, type, options, fn);
param(options);
param(options, fn);

Come si scrive un prototipo di funzione (documentazione) per questi tipi di metodi (anche quelli che non arrivano a questo estremo)?

Alcuni progetti utilizzano la funzione "overloading" nella documentazione:

.on(event, fn, [capture])
.on(event, selector, fn, [capture])

Ma la lunghezza verrebbe compensata dalla chiarezza o dalla flessibilità?

functions javascript documentation

posta Daniel 26.04.2013 - 01:11

fonte

1 risposta

Leggi altre domande sui tag functions javascript documentation

Standard web nascosti dietro Google "custom searchEngines"? Approccio SDLC per progetti di piccole dimensioni

score 5 · Accepted Answer

Il motivo per cui i progetti utilizzano la sintassi di overload è perché è facile e chiaro da leggere. Potrebbero esserci critiche sulla libreria jQuery ma è una delle migliori librerie documentate che conosca in JavaScript, è molto facile da leggere.

Le funzioni in questa sintassi hanno due scopi, o gli argomenti sono facoltativi (come passare le opzioni a $ .get in jQuery) o gli argomenti cambiano ciò che la funzione fa (sovraccarico) . Questi due casi sono fondamentalmente diversi!

Guarda come ad esempio in jQuery la funzione .css è divisa in:

.css( propertyName ) // gets a property value

.css( propertyName, value ) //sets a property value

Eseguono compiti fondamentalmente diversi e devono essere documentati come metodi diversi.

Al contrario il metodo $.get esegue la stessa azione ma ha prameters opzionali, motivo per cui è documentato come tale:

jQuery.get( url [, data ] [, success(data, textStatus, jqXHR) ] [, dataType ] )

Questo ci rende chiaro che l'azione eseguita è fondamentalmente la stessa ma i parametri facoltativi ci danno suggerimenti su cosa possiamo passare al metodo.