Jak dodać przykłady do dokumentacji interfejsu API w programie Go?

Question

Jest kilka fajnych executable examples w standardowej bibliotece Go. Jak mogę dodać taki przykład do mojej własnej dokumentacji API?

Answer 1

Wyjście $ go help testfunc:

do 'przejść test' komenda spodziewa się znaleźć test, wzorzec i przykład funkcjonuje w "* _test.go" plików odpowiadających pakietu badanego.

Funkcja Test jest jeden o nazwie TestXXX (gdzie xxx jest dowolny ciąg alfanumeryczny nie wychodząc z małej litery) i powinno mieć podpis,

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

Wyjściowa funkcja jest jeden o nazwie BenchmarkXXX i powinien mieć podpis,

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

Przykładowa funkcja jest podobna do funkcji testowej, ale zamiast używać * testing.T do zgłaszania sukcesu lub niepowodzenia, drukuje dane wyjściowe do os.Stdout i os.Stderr. Dane wyjściowe są porównywane z komentarzem funkcji "Wyjście:", który to numer musi być ostatnim komentarzem w treści funkcji (patrz przykład poniżej). Przykład bez takiego komentarza lub bez tekstu po "Wyjście:" jest kompilowany , ale nie został wykonany.

Godoc wyświetla treść przykładu XXX, demonstrując użycie funkcji, stałej lub zmiennej XXX. Przykład metody M z odbiornikiem typu T lub * T ma nazwę ExampleT_M. Może istnieć wiele przykładów dla danej funkcji, stałej lub zmiennej, rozróżnianych przez końcowe _xxx, gdzie xxx jest sufiksem nie rozpoczynającym się od dużej litery.

Oto przykładem np

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

Cały plik testu jest przedstawiona jako przykład, jeśli zawiera pojedynczą przykład funkcji co najmniej jedna funkcja typu zmienny lub stała deklaracja i brak funkcji testowania lub testów porównawczych.

Zobacz dokumentację pakietu testowego, aby uzyskać więcej informacji.