Come aggiungere esempi alla documentazione dell'API in Go?

Question

Nella libreria standard Go ci sono alcuni bei executable examples. Come posso aggiungere un esempio alla mia documentazione API?

Answer 1

uscita di $ go help testfunc:

Il 'go test' di comando si aspetta di trovare prova, punto di riferimento, e l'esempio funziona nelle "* _test.go" file corrispondente al pacchetto in prova.

Una funzione di test è un nome testXXX (dove XXX è un qualsiasi stringa alfanumerica che non inizia con una lettera minuscola) e dovrebbe avere la firma,

func TestXXX(t *testing.T) { ... } 

Una funzione di riferimento è uno di nome BenchmarkXXX e dovrebbe avere la firma,

func BenchmarkXXX(b *testing.B) { ... } 

Una funzione di esempio è simile a una funzione di test ma, anziché utilizzare * testing.T per segnalare l'esito positivo o negativo, stampa l'output su os.Stdout e os.Stderr. Tale output viene confrontato con il commento "Output:" della funzione, che deve essere l'ultimo commento nel corpo della funzione (vedere l'esempio di seguito). Un esempio senza tale commento, o senza testo dopo "Output:" è compilato ma non eseguito.

Godoc visualizza il corpo di ExampleXXX per dimostrare l'uso di della funzione, costante o variabile XXX. Un esempio di un metodo M con il tipo di ricevitore T o * T è denominato ExampleT_M. Potrebbero esserci più esempi per una determinata funzione, costante o variabile, contraddistinta da un trailing _xxx, dove xxx è un suffisso che non inizia con una lettera maiuscola.

Ecco un esempio di un esempio:

func ExamplePrintln() { 
     Println("The output of\nthis example.") 
     // Output: The output of 
     // this example. 
} 

L'intero file di prova è presentata come esempio quando contiene una singola funzione esempio, almeno un'altra funzione, tipo, variabile , o costante dichiarazione , e nessuna funzione di test o benchmark.

Vedere la documentazione del pacchetto di test per ulteriori informazioni.