Go dokumentatsiyasini yozish va o‘qish

Go dokumentatsiyasi manba kodidagi izohlardan hosil bo‘ladi. Yaxshi izoh nomni takrorlash bilan cheklanmaydi: u API nima qilishi, muhim cheklovi va xato holatini tushuntiradi.

Eksport qilinadigan nomlar izohi

Katta harf bilan boshlangan package-level nom boshqa paketlarga eksport qilinadi. Uning izohi odatda nomning o‘zi bilan boshlanadi:

// User tizim foydalanuvchisini ifodalaydi.
type User struct {
    Name string
}

// NewUser berilgan nom bilan yangi User qaytaradi.
func NewUser(name string) User {
    return User{Name: name}
}

// DisplayName foydalanuvchining ko‘rsatiladigan nomini qaytaradi.
func (u User) DisplayName() string {
    return u.Name
}

Nom bilan boshlanish go doc chiqishini o‘qishni yengillashtiradi. Izohda koddan aniq ko‘rinib turgan implementatsiyani emas, chaqiruvchi bilishi kerak bo‘lgan xatti-harakatni yozing.

Package comment

Package comment package deklaratsiyasidan oldin yoziladi va Package <nom> bilan boshlanadi:

// Package greeting turli tillarda salomlashish funksiyalarini beradi.
package greeting

Kichik paketda izoh istalgan oddiy .go faylda turishi mumkin. Kengroq dokumentatsiya uchun uni doc.go faylida saqlash qulay. Bitta paket uchun qarama-qarshi bir nechta package comment yozmang.

go doc bilan o‘qish

Terminaldan lokal va dependency dokumentatsiyasini ko‘rish mumkin:

go doc fmt
go doc fmt.Println
go doc ./...

go doc fmt paket tavsifi va eksport qilingan API’ni, go doc fmt.Println esa aniq funksiyani ko‘rsatadi. go doc ./... joriy modul paketlarini ko‘rib chiqadi.

Standart kutubxona va ochiq modullar dokumentatsiyasini pkg.go.dev saytidan ham o‘qish mumkin. U package API’si, manba havolalari, versiyalar va import qiluvchi modullar haqida ma’lumot beradi.

Misol funksiyalari

Example funksiyasi ishlaydigan dokumentatsiya misoli bo‘lib, _test.go faylida yoziladi:

greeting_test.go

package greeting_test

import (
    "fmt"

    "example.com/demo/greeting"
)

func ExampleHello() {
    fmt.Println(greeting.Hello("Ali"))
    // Output: Salom, Ali!
}

// Output: mavjud bo‘lsa, go test funksiyani bajaradi va stdout natijasini izohdagi qiymat bilan solishtiradi. ExampleHello package misoli, ExampleUser tur misoli, ExampleUser_DisplayName esa method misoli sifatida bog‘lanadi.

Misol ixcham bo‘lsin va API’dan odatiy foydalanishni ko‘rsatsin. Tasodifiy vaqt, map tartibi yoki tarmoq kabi beqaror natijaga tayanmang.

Xulosa

Eksport qilinadigan nom izohini o‘sha nom bilan boshlang va chaqiruvchi uchun muhim xatti-harakatni tushuntiring. Dokumentatsiyani go doc yoki pkg.go.dev orqali o‘qing. Example funksiyalari esa tekshiriladigan misol va dokumentatsiyani bir joyda saqlaydi.