From 669d4ec0d9f7809e28ffc3fe7be1a1c3725dcdf6 Mon Sep 17 00:00:00 2001 From: Shulhan Date: Thu, 18 Mar 2021 03:20:03 +0700 Subject: blog: terjemahkan artikel "Godoc: documenting Go code" --- _content/blog/godoc/index.adoc | 136 +++++++++++++++++++++++++++++++++++++++++ _content/blog/index.adoc | 4 ++ 2 files changed, 140 insertions(+) create mode 100644 _content/blog/godoc/index.adoc diff --git a/_content/blog/godoc/index.adoc b/_content/blog/godoc/index.adoc new file mode 100644 index 0000000..634b232 --- /dev/null +++ b/_content/blog/godoc/index.adoc @@ -0,0 +1,136 @@ += godoc: Mendokumentasikan kode Go +Andrew Gerrand +31 Maret 2011 + +Proyek Go melakukan dokumentasi dengan serius. +Dokumentasi adalah bagian terbesar yang membuat perangkat lunak mudah diakses +dan dijaga. +Tidak saja dokumentasi harus ditulis dengan baik dan akurat, ia juga harus +mudah ditulis dan dijaga. +Idealnya, dokumentasi sebaiknya tercakup dalam kode itu sendiri sehingga +dokumentasi berkembang bersama dengan kode. +Semakin mudah bagi pemogram untuk menghasilkan dokumentasi yang bagus, maka +semakin baik hal itu bagi semua orang. + +Oleh karena itu, kita telah mengembangkan perkakas dokumentasi +https://golang.org/cmd/godoc/[`godoc`^]. +Artikel ini menjelaskan pendekatan `godoc` terhadap dokumentasi, dan +menjelaskan bagaimana Anda dapat menggunakan konvensi dan perkakas tersebut +untuk menulis dokumentasi yang bagus untuk proyek Anda. + +Godoc mengurai kode sumber --termasuk komentar-- dan menghasilkan dokumentasi +dalam bentuk HTML atau teks. +Hasil akhirnya yaitu dokumentasi yang berkaitan erat dengan kode yang +didokumentasikan. +Sebagai contohnya, lewat antar muka web dari godoc anda dapat melakukan +navigasi dari dokumentasi +https://golang.org/pkg/strings/#HasPrefix[sebuah fungsi^] +ke +https://golang.org/src/strings/strings.go?s=11163:11200#L434[implementasinya^] +lewat satu klik. + +Secara konseptual, godoc mirip dengan +https://www.python.org/dev/peps/pep-0257/[Docstring^] +pada Python dan +https://www.oracle.com/java/technologies/javase/javadoc-tool.html[Javadoc^] +pada Java, namun lebih simpel. +Komentar yang dibaca oleh godoc bukanlah konstruksi bahasa (seperti pada +Docstring) dan tidak harus memiliki sintak yang bisa dibaca mesin (seperti +pada Javadoc). +Komentar pada godoc cukup dengan tulisan yang baik, tulisan yang ingin Anda +baca bahkan tanpa godoc. + +Konvensinya cukup sederhana: untuk mendokumentasikan sebuah tipe, variabel, +konstan, fungsi, atau bahkan sebuah paket, tulis lah komentar tersebut +langsung di atas deklarasinya, tanpa ada baris kosong. +Godoc kemudian akan mempresentasikan komentar tersebut sebagai teks bersama +dengan item yang didokumentasikan. +Sebagai contohnya, berikut dokumentasi untuk fungsi +https://golang.org/pkg/fmt/#Fprint[`Fprint`^] pada paket `fmt`: + + // Fprint formats using the default formats for its operands and writes to w. + // Spaces are added between operands when neither is a string. + // It returns the number of bytes written and any write error encountered. + func Fprint(w io.Writer, a ...interface{}) (n int, err error) { + +Perhatikan komentar tersebut adalah sebuah kalimat lengkap yang dimulai dengan +nama dari elemen yang dijelaskan. +Konvensi ini penting dan membolehkan kita menghasilkan dokumentasi dalam +format yang beragam, dari teks sampai HTML sampai halaman `man` pada UNIX, +dan membuatnya mudah dibaca saat sebuah perkakas memotong komentar tersebut, +seperti saat mengekstrak baris atau kalimat yang pertama. + +Komentar pada deklarasi paket sebaiknya menyediakan dokumentasi paket secara +keseluruhan. +Komentar tersebut bisa saja pendek, seperti deskripsi pada paket +https://golang.org/pkg/sort/[`sort`^]. + + // Package sort provides primitives for sorting slices and user-defined + // collections. + package sort + +Komentar pada paket juga dapat sangat detil seperti pada paket +https://golang.org/pkg/encoding/gob/[gob^]. +Paket tersebut menggunakan konvensi: jika dokumentasi paket terlalu panjang +maka komentar ditaruh diberkasnya sendiri, +https://golang.org/src/pkg/encoding/gob/doc.go[doc.go^], +yang berisi hanya komentar dan sebuah klausa paket. + +Saat menulis komentar untuk sebuah paket, ingatlah selalu bahwa kalimat +pertama akan muncul dalam +https://golang.org/pkg/[daftar paket^] +di godoc. + +Komentar yang tidak selaras dengan deklarasinya akan diindahkan dari keluaran +godoc, dengan sebuah pengecualian. +Komentar teratas yang dimulai dengan kata `"BUG(who)"` dikenali sebagai "bug" +yang tercatat, dan diikutkan dalam bagian "Bugs" dari dokumentasi paket. +Bagian "who" diisi dengan nama orang yang bisa menyediakan informasi lebih +lanjut tentang _bug_ tersebut. +Sebagai contohnya, berikut adalah isu yang tercatat pada +https://golang.org/pkg/bytes/#pkg-note-BUG[paket bytes^]: + + // BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly. + +Terkadang sebuah field pada struct, fungsi, tipe, atau bahkan keseluruhan +paket sudah tidak digunakan lagi, tetapi harus tetap disimpan demi +kompatibilitas dengan program yang ada. +Untuk menginformasikan bahwa sebuah pengidentifikasi sebaiknya tidak digunakan +lagi, tambahkan sebuah paragraf pada komentar yang dimulai dengan +"Deprecated:" diikuti dengan informasi tentang kenapa ia tidak digunakan lagi. +Ada beberapa contoh +https://golang.org/search?q=Deprecated:[pada pustaka standar^]. + +Ada beberapa aturan format yang Godoc gunakan saat mengonversi komentar ke +HTML: + +* Baris selanjutnya dari teks dianggap bagian dari paragraf yang sama; Anda + harus meninggalkan baris kosong untuk memisahkan paragraf. + +* Pra-format teks dibentuk dengan memberi spasi dengan tab relatif terhadap + teks komentar disekitarnya (lihat dokumentasi + https://golang.org/src/pkg/encoding/gob/doc.go[doc.go^] sebagai + contohnya). + +* URL akan dikonversi ke tautan HTML; tidak ada marka khusus yang perlu + ditambahkan. + +Ingat bahwa tidak ada dari aturan-aturan tersebut yang mengharuskan Anda +melakukan sesuatu yang khusus. + +Faktanya, hal terbaik dari pendekatan minimal godoc yaitu bagaimana mudahnya +ia digunakan. +Akibatnya, banyak kode Go, termasuk semua pustaka standar, telah mengikuti +konvensi-konvensi tersebut. + +Kode Anda sendiri dapat merepresentasikan dokumentasi yang bagus dengan hanya +memberi komentar seperti yang dijelaskan di atas. +Setiap paket Go yang dipasang dalam `$GOROOT/src/pkg` dan setiap ruang kerja +`GOPATH` akan dapat diakses lewat baris-perintah `godoc` dan antar muka +HTTP, dan Anda dapat menentukan direktori-direktori tambahan untuk +pengindeksan lewat opsi `-path` atau hanya dengan menjalankan `"godoc ."` di +dalam direktori sumber. + +Lihatlah +https://golang.org/cmd/godoc/[dokumentasi godoc^] +untuk lebih jelasnya. diff --git a/_content/blog/index.adoc b/_content/blog/index.adoc index 25ef76a..fd5f9f8 100644 --- a/_content/blog/index.adoc +++ b/_content/blog/index.adoc @@ -70,6 +70,10 @@ goprotobuf dan lainnya], 20 April 2010. _Andrew Gerrand_ +* link:/blog/godoc/[godoc: Mendokumentasikan kode Go], + 31 Maret 2011. _Andrew Gerrand_ + + == Bahasa * link:/blog/gos-declaration-syntax/[Sintaksis deklarasi pada Go] -- cgit v1.3