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.

Misollar

1. Bajariladigan paketga izoh yozish

Bu misolda package comment main paketining vazifasini tushuntiradi.

// Package main terminalga salomlashish xabarini chiqaradigan dasturni beradi.
package main

import "fmt"

func main() {
    fmt.Println("Salom, Go!")
}

go mod init example.com/package-comment
go doc .
go run .

Package comment package main deklaratsiyasidan bevosita oldin yozilgan va Package main bilan boshlangan. go doc . joriy paket tavsifini chiqaradi. Izoh dastur natijasini emas, paketning umumiy vazifasini aytadi.

2. Funksiya natijasini hujjatlashtirish

Bu misolda eksport qilinadigan funksiya izohi uning nomi va qaytaradigan qiymatini tushuntiradi.

package main

import "fmt"

// Greeting berilgan ism uchun salomlashish matnini qaytaradi.
// Bo‘sh ism berilsa, "Salom, mehmon!" qaytariladi.
func Greeting(name string) string {
    if name == "" {
        return "Salom, mehmon!"
    }
    return "Salom, " + name + "!"
}

func main() {
    fmt.Println(Greeting("Ali"))
}

go mod init example.com/function-doc
go doc -cmd . Greeting
go run .

Izoh Greeting nomi bilan boshlanadi. Ikkinchi satr bo‘sh matnning alohida ma’nosini ko‘rsatadi. Bu ma’lumot funksiya tanasini o‘qimasdan turib natijani tushunishga yordam beradi.

3. Xato holatini izohda ko‘rsatish

Bu misolda funksiya qaysi holatda error qaytarishi dokumentatsiyada aniq yoziladi.

package main

import (
    "errors"
    "fmt"
)

// Divide a qiymatini b qiymatiga bo‘ladi.
// b nol bo‘lsa, Divide xato qaytaradi.
func Divide(a, b float64) (float64, error) {
    if b == 0 {
        return 0, errors.New("nolga bo‘lish mumkin emas")
    }
    return a / b, nil
}

func main() {
    result, err := Divide(10, 2)
    if err != nil {
        fmt.Println("Xato:", err)
        return
    }
    fmt.Println(result)
}

go mod init example.com/error-doc
go doc -cmd . Divide
go run .

Chaqiruvchi uchun muhim cheklov b nol bo‘lishi bilan bog‘liq. Xato holatida float64 turning nol qiymati 0 qaytariladi, lekin chaqiruvchi avval errni tekshirishi kerak.

4. Tur va metodni hujjatlashtirish

Bu misolda eksport qilinadigan tur, maydon va metodning har biri alohida izohlanadi.

package main

import "fmt"

// Account foydalanuvchining hisob ma’lumotlarini saqlaydi.
type Account struct {
    // Name hisob egasining ko‘rsatiladigan nomi.
    Name string
    // Balance hisobdagi joriy mablag‘ni bildiradi.
    Balance int
}

// CanPay hisobda berilgan summa uchun mablag‘ yetarliligini bildiradi.
func (a Account) CanPay(amount int) bool {
    return amount >= 0 && a.Balance >= amount
}

func main() {
    account := Account{Name: "Ali", Balance: 100}
    fmt.Println(account.CanPay(60))
}

go mod init example.com/type-doc
go doc -cmd . Account
go doc -cmd . Account.CanPay
go run .

Account izohi turning vazifasini, maydon izohlari esa qiymatlarning ma’nosini beradi. CanPay()da amount >= 0 manfiy summani haqiqiy to‘lov deb qabul qilmaslik uchun ishlatiladi.

5. Konstantalar guruhini izohlash

Bu misolda umumiy izoh konstantalar guruhining vazifasini, satr izohlari esa alohida qiymatlarni tushuntiradi.

package main

import "fmt"

type Status int

// Buyurtma holatlari qayta ishlash bosqichlarini bildiradi.
const (
    StatusUnknown  Status = iota // StatusUnknown hali holat tanlanmaganini bildiradi.
    StatusAccepted               // StatusAccepted buyurtma qabul qilinganini bildiradi.
    StatusSent                   // StatusSent buyurtma yuborilganini bildiradi.
)

func main() {
    fmt.Println(StatusAccepted)
}

go mod init example.com/const-doc
go doc -cmd . Status
go run .

StatusUnknown 0 qiymatida turadi, chunki Statusning nol qiymati noma’lum holatni bildirishi kerak. Guruh izohi qiymatlarning umumiy mavzusini aytadi. Har bir satr izohi esa qiymatlar orasidagi farqni ko‘rsatadi.

6. Eksport qilinadigan o‘zgaruvchini izohlash

Bu misolda package-level o‘zgaruvchining birligi va standart qiymati izohda ko‘rsatiladi.

package main

import "fmt"

// DefaultLimit bitta so‘rovda qaytariladigan elementlarning standart soni.
var DefaultLimit = 20

func main() {
    fmt.Println("Limit:", DefaultLimit)
}

go mod init example.com/variable-doc
go doc -cmd . DefaultLimit
go run .

DefaultLimit nomi qiymat nima ekanini aytadi, izoh esa uning qayerda ishlatilishini tushuntiradi. 20 kichik natija sahifasi uchun namunaviy standart qiymat sifatida tanlangan.

7. Boshqa nomga dokumentatsiya havolasi berish

Bu misolda kvadrat qavs ichidagi nom go doc tomonidan shu paketdagi turga havola sifatida taniladi.

package main

import "fmt"

// Config dastur sozlamalarini saqlaydi.
type Config struct {
    Port int
}

// DefaultConfig yangi [Config] uchun xavfsiz boshlang‘ich qiymatlarni qaytaradi.
func DefaultConfig() Config {
    return Config{Port: 8080}
}

func main() {
    fmt.Println(DefaultConfig().Port)
}

go mod init example.com/doc-link
go doc -cmd . DefaultConfig
go run .

[Config] oddiy matnni shu paketdagi Config dokumentatsiyasiga bog‘laydi. 8080 faqat misoldagi standart port; haqiqiy loyiha talabiga qarab boshqa qiymat tanlanishi mumkin.

8. Izohni sarlavha va ro‘yxatga ajratish

Bu misolda uzunroq package comment kichik bo‘lim va ro‘yxat bilan tuziladi.

// Package main buyurtma holatini terminalga chiqaradi.
//
// # Holatlar
//
// Dastur quyidagi qiymatlardan foydalanadi:
//
//   - new — yangi buyurtma;
//   - sent — yuborilgan buyurtma.
package main

import "fmt"

func main() {
    fmt.Println("new")
}

go mod init example.com/structured-doc
go doc .
go run .

Bo‘sh komment satrlari abzatslarni ajratadi. # Holatlar sarlavha, bo‘shliq bilan surilgan satrlar esa ro‘yxat sifatida ko‘rsatiladi. Bunday tuzilma faqat izoh bir nechta mustaqil fikrni tushuntirganda kerak.

9. Eskirgan API’ni belgilash

Bu misolda eski funksiya saqlanadi, lekin dokumentatsiya foydalanuvchini yangi nomga yo‘naltiradi.

package main

import "fmt"

// NewGreeting berilgan ism uchun salomlashish qaytaradi.
func NewGreeting(name string) string {
    return "Salom, " + name
}

// OldGreeting berilgan ism uchun salomlashish qaytaradi.
//
// Deprecated: NewGreeting funksiyasidan foydalaning.
func OldGreeting(name string) string {
    return NewGreeting(name)
}

func main() {
    fmt.Println(OldGreeting("Ali"))
}

go mod init example.com/deprecated-doc
go doc -cmd . OldGreeting
go run .

Deprecated: alohida abzats boshida yoziladi. Eski funksiya hozircha ishlaydi, shu sabab mavjud chaqiruvlar buzilmaydi. Izoh esa yangi kodda NewGreeting() tanlanishi kerakligini ko‘rsatadi.

10. Dokumentatsiya bilan birga manbani ko‘rish

Bu misolda go doc -src eksport qilingan funksiya izohi va manba kodini birga chiqaradi.

package main

import "fmt"

// NormalizeCount manfiy qiymatni nolga almashtiradi.
func NormalizeCount(count int) int {
    if count < 0 {
        return 0
    }
    return count
}

func main() {
    fmt.Println(NormalizeCount(-3))
}

go mod init example.com/source-doc
go doc -src -cmd . NormalizeCount
go run .

go doc -src API qanday e’lon qilinganini va uning implementatsiyasini ko‘rishga yordam beradi. count < 0 faqat manfiy qiymatlarni almashtiradi; 0 haqiqiy nol miqdor sifatida o‘zgarishsiz qaytadi.