go doc

Setiap identifier di standard library menyimpan dokumentasi yang bisa dibaca tanpa membuka browser: komentar yang tertata rapi di atas deklarasi diolah menjadi dokumentasi oleh tooling Go. Perintah go doc mencetak dokumentasi tersebut langsung di terminal, dan aturan yang sama bekerja dua arah — komentar yang kita tulis pada kode sendiri otomatis menjadi dokumentasi untuk pemakai package kita. Pada chapter ini kita akan membaca dokumentasi fmt.Println dan net/http.ServeMux, mempelajari konvensi komentar godoc, lalu melihat dokumentasi package buatan sendiri tampil di go doc.

Membaca Dokumentasi dari Terminal #

Ketika kita lupa perilaku pasti sebuah fungsi, go doc adalah cara tercepat memastikannya tanpa meninggalkan terminal:

bash

go doc fmt.Println

Output yang Dihasilkan:

text
package fmt // import "fmt"

func Println(a ...any) (n int, err error)
    Println formats using the default formats for its operands and writes to
    standard output. Spaces are always added between operands and a newline
    is appended. It returns the number of bytes written and any write error
    encountered.

Anatomi keluaran di atas terdiri atas tiga bagian. Baris pertama memuat package dan import path tempat identifier berada. Baris kedua adalah tanda tangan lengkap — kita langsung tahu Println menerima sejumlah argumen any dan mengembalikan jumlah byte plus error. Sisanya adalah paragraf dokumentasi, yang pada standard library tertulis dalam bahasa Inggris. Perhatikan bahwa kalimat pertama paragraf dimulai dengan nama Println — ini bukan kebetulan, melainkan konvensi yang akan kita bahas sebentar lagi.

Menyempitkan dan Menampilkan Struktur #

Dokumentasi sebuah type bisa sangat panjang. Perintah go doc net/http.ServeMux mencetak deskripsi lengkap ServeMux beserta seluruh aturan pattern-nya — puluhan baris. Dua flag membantu menyaringnya:

bash

go doc -short net/http.ServeMux

Output yang Dihasilkan:

text

type ServeMux struct{ ... }

Flag -short memangkas seluruh paragraf dan hanya menyisakan ringkasan deklarasi. Sebaliknya, jika yang kita butuhkan hanya satu method, sebutkan langsung nama lengkapnya:

bash

go doc net/http.ServeMux.HandleFunc

Output yang Dihasilkan:

text
package http // import "net/http"

func (mux *ServeMux) HandleFunc(pattern string, handler func(ResponseWriter, *Request))
    HandleFunc registers the handler function for the given pattern. If the
    given pattern conflicts with one that is already registered or if the
    pattern is invalid, HandleFunc panics.

    See ServeMux for details on valid patterns and conflict rules.

Dengan kombinasi package, type, dan nama method, go doc menampilkan tepat bagian yang dicari — jauh lebih presisi daripada membuka dokumentasi web dan menggulir manual.

Konvensi Komentar godoc #

Dokumentasi fmt.Println tampil rapi karena komentarnya mengikuti konvensi godoc. Aturannya ringkas: komentar dokumentasi ditulis tepat di atas deklarasi tanpa baris kosong pemisah, dan kalimat pertamanya diawali nama identifier yang didokumentasikan. Bandingkan dua gaya berikut:

go
// fungsi ini menjumlahkan harga
func HitungTotal(harga []int, member bool) int {

go
// HitungTotal menjumlahkan seluruh harga item, lalu memberi potongan
// DiskonMember persen bila pembeli adalah member.
func HitungTotal(harga []int, member bool) int {

Komentar pertama buruk karena pembaca harus menebak fungsi mana yang dimaksud dan klaimnya tidak berbentuk kalimat utuh. Komentar kedua baik: kalimat pembukanya bisa dipotong menjadi satu baris ringkas di daftar (seperti yang tampil pada go doc ./kasir nanti), dan paragrafnya menjelaskan parameter yang membutuhkan penjelasan. Konvensi tambahan yang penting: awali komentar package dengan kata Package diikuti nama package, tandai API lama dengan // Deprecated:, dan gunakan kalimat utuh berhenti di titik karena tool pemotong dokumentasi mengandalkan tanda baca tersebut.

Dokumentasi Package Buatan Sendiri #

Aturan yang sama bekerja untuk kode kita. Modul uji example.com/aplikasidoc berisi package kasir dengan komentar konvensi godoc:

go
// Package kasir menghitung total belanja dan potongan harga
// untuk transaksi kasir sederhana.
package kasir

// DiskonMember adalah persentase potongan harga bagi anggota
// toko, dinyatakan dalam bilangan bulat 0 sampai 100.
const DiskonMember = 10

// HitungTotal menjumlahkan seluruh harga item, lalu memberi
// potongan DiskonMember persen bila pembeli adalah member.
// Parameter member bernilai true untuk anggota toko.
func HitungTotal(harga []int, member bool) int {

Dari direktori akar module, dokumentasinya dapat dibaca dengan path relatif:

bash

go doc ./kasir

Output yang Dihasilkan:

text
package kasir // import "example.com/aplikasidoc/kasir"

Package kasir menghitung total belanja dan potongan harga untuk transaksi kasir
sederhana.

const DiskonMember = 10
func HitungTotal(harga []int, member bool) int

bash

go doc ./kasir HitungTotal

Output yang Dihasilkan:

text
package kasir // import "example.com/aplikasidoc/kasir"

func HitungTotal(harga []int, member bool) int
    HitungTotal menjumlahkan seluruh harga item, lalu memberi potongan
    DiskonMember persen bila pembeli adalah member. Parameter member bernilai
    true untuk anggota toko.

Komentar yang kita tulis tampil utuh sebagai dokumentasi — tanpa generator, tanpa berkas terpisah. Berkas contoh.go pada bagian bawah halaman mempraktikkan konvensi ini pada program utuh. Seluruh berkas berbunyi:

go
package main

import "fmt"

// DiskonMember adalah persentase potongan harga bagi anggota toko,
// dinyatakan dalam bilangan bulat 0 sampai 100.
const DiskonMember = 10

// HitungTotal menjumlahkan seluruh harga item, lalu memberi potongan
// DiskonMember persen bila pembeli adalah member.
// Parameter member bernilai true untuk anggota toko.
func HitungTotal(harga []int, member bool) int {
	total := 0
	for _, h := range harga {
		total += h
	}
	if member {
		total -= total * DiskonMember / 100
	}
	return total
}

func main() {
	fmt.Println("Total:", HitungTotal([]int{15000, 25000}, true))
}

Jalankan dengan perintah berikut:

bash

go run contoh.go

Output yang Dihasilkan:

text

Total: 36000

Dokumentasi kini hidup berdampingan dengan kode. Selanjutnya kita beranjak ke tool yang menulis kode untuk kita: go generate untuk membangkitkan berkas sumber dari directive.

Referensi #

Go doc comments — dokumentasi resmi — aturan lengkap penulisan komentar godoc.
Dokumentasi perintah go — referensi go doc dan seluruh subperintahnya.

Berkas Sumber

Berkas pendukung halaman ini dapat diunduh dan dijalankan langsung sesuai penjelasan di atas.

go
package main

import "fmt"

// DiskonMember adalah persentase potongan harga bagi anggota toko,
// dinyatakan dalam bilangan bulat 0 sampai 100.
const DiskonMember = 10

// HitungTotal menjumlahkan seluruh harga item, lalu memberi potongan
// DiskonMember persen bila pembeli adalah member.
// Parameter member bernilai true untuk anggota toko.
func HitungTotal(harga []int, member bool) int {
	total := 0
	for _, h := range harga {
		total += h
	}
	if member {
		total -= total * DiskonMember / 100
	}
	return total
}

func main() {
	fmt.Println("Total:", HitungTotal([]int{15000, 25000}, true))
}