Tài liệu Go Code tự động sử dụng Godoc
Khi bạn nghĩ về lập trình, điều tự nhiên là tập trung vào các chủ đề như ngôn ngữ, thuật toán và gỡ lỗi. Nhưng tài liệu kỹ thuật cũng quan trọng không kém để làm đúng.
Nếu không có tài liệu tốt, khả năng tái sử dụng mã có thể bị ảnh hưởng. Người dùng mới làm quen với cơ sở mã có thể dễ dàng bị lạc hoặc thất vọng nếu tài liệu không được cập nhật. Điều quan trọng không chỉ là hiểu những gì một chương trình thực hiện, mà còn làm thế nào — hoặc thậm chí tại sao — chương trình đó hoạt động như thế nào.
Các gói như Pydoc cho Python và Javadoc cho Java trợ giúp bằng cách tự động hóa một phần của quy trình. Công cụ Godoc cũng làm như vậy đối với cờ vây.
Mục Lục
Godoc là gì?
Godoc là một gói Go cho phép bạn tạo, quản lý và sử dụng tài liệu Go trong “the Go way”. Cờ vây là một tập hợp các nguyên tắc mà với tư cách là một lập trình viên cờ vây, bạn nên tuân theo để cải thiện chất lượng mã.
Sử dụng Godoc, bạn có thể dễ dàng đọc tài liệu và mã của các nhà phát triển khác. Bạn cũng có thể tự động tạo tài liệu của riêng mình và xuất bản bằng Godoc.
Godoc tương tự như Javadoc, trình tài liệu mã cho Java. Cả hai đều sử dụng nhận xét và mã trong mô-đun để tạo tài liệu. Và cả hai công cụ đều cấu trúc tài liệu đó bằng HTML để bạn có thể xem nó trong trình duyệt.
Bắt đầu với Godoc
Sử dụng Godoc rất dễ dàng. Để bắt đầu, hãy cài đặt gói Godoc từ trang web golang bằng lệnh sau:
go get golang.org/x/tools/cmd/godoc
Chạy lệnh này sẽ cài đặt Godoc trong không gian làm việc được chỉ định của bạn. Sau khi hoàn thành, bạn sẽ có thể chạy thần thánh lệnh trong một thiết bị đầu cuối. Nếu có bất kỳ lỗi nào với quá trình cài đặt của bạn, hãy thử cập nhật Lên phiên bản gần đây.
Godoc tìm kiếm các nhận xét đơn và nhiều dòng để đưa vào tài liệu mà nó tạo ra.
Đảm bảo định dạng mã cho Cờ vây, như được giải thích trong ấn phẩm Cờ vây hiệu quả của nhóm Cờ vây để có kết quả tốt nhất.
Dưới đây là một ví dụ sử dụng các chú thích một dòng kiểu C ++:
type User struct {}
Bạn cũng có thể sử dụng nhận xét khối kiểu C:
User is a custom data structureYou can include any text here and the Godoc server will format it when you run it.
*/
type User struct {
}
Trong các nhận xét ở trên, “Người dùng” bắt đầu các câu vì nhận xét mô tả chức năng của cấu trúc Người dùng. Đây là một trong nhiều chủ đề mà Cờ vây bàn luận. Bắt đầu các câu tài liệu với một tên hữu ích là rất quan trọng vì câu đầu tiên xuất hiện trong danh sách gói.
Chạy máy chủ Godoc
Khi bạn đã nhận xét mã của mình, bạn có thể chạy thần thánh lệnh trong thiết bị đầu cuối của bạn, từ thư mục mã của dự án của bạn.
Thông thường, các nhà phát triển cờ vây sử dụng cổng 6060 để lưu trữ tài liệu. Đây là lệnh để chạy máy chủ Godoc trên cổng đó:
godoc -http=:6060
Lệnh trên lưu trữ tài liệu mã của bạn trên localhost hoặc 127.0.0.1. Cổng không phải là 6060; Godoc sẽ chạy trên bất kỳ cổng nào chưa có người sử dụng. Tuy nhiên, tốt nhất bạn nên tuân theo các quy ước về tài liệu Go.
Khi bạn đã chạy lệnh, bạn có thể xem tài liệu của mình trong trình duyệt bằng cách truy cập localhost: 6060. Thời gian Godoc cần để tạo tài liệu của bạn sẽ phụ thuộc vào kích thước và độ phức tạp của nó.
Đoạn mã dưới đây tuân theo Cách đi, trong trường hợp này là sử dụng chú thích một dòng.
package user
import (
"fmt"
)
type User struct {
Age int
Name string
}
func main() {
human := User {
Age: 0,
Name: "person",
}
fmt.Println(human.Talk())
}
func (receiver User) Talk() string {
return "Every User Gets to Say Something!"
}
Nếu bạn chạy Godoc trên mô-đun mã ở trên, bạn sẽ thấy đầu ra giống như sau:
Lưu ý rằng nó có định dạng quen thuộc, tương tự như những gì bạn sẽ tìm thấy trên trang web tài liệu chính thức của Go.
Godoc sử dụng chú thích trước khai báo gói làm Tổng quan. Đảm bảo rằng nhận xét này mô tả những gì chương trình của bạn làm.
Các Mục lục chứa các liên kết đến các khai báo kiểu và phương thức để bạn có thể điều hướng đến chúng một cách nhanh chóng.
Godoc cũng cung cấp chức năng để xem mã nguồn tạo nên gói trong Gói tệp tiết diện.
Cải thiện tài liệu của bạn bằng Godoc
Bạn có thể bao gồm nhiều hơn chỉ là văn bản đơn thuần trong tài liệu Godoc của mình. Bạn có thể thêm các URL mà Godoc sẽ tạo liên kết và cấu trúc nhận xét của bạn thành các đoạn văn.
Nếu bạn muốn liên kết đến một tài nguyên, hãy viết URL vào bình luận của bạn, và Godoc sẽ nhận ra nó và thêm một liên kết. Đối với các đoạn văn, hãy để lại một dòng chú thích trống.
package main
type Document struct {
pages int
references string
signed bool
}
func Write() {
}
Lưu ý rằng Godoc yêu cầu bạn viết đầy đủ các URL để nó liên kết chúng. Trong ví dụ này, URL của Google bao gồm https: // tiền tố, vì vậy Godoc thêm một liên kết vào nó. Vì tên miền Wikipedia không phải là một URL đầy đủ, nên Godoc sẽ để nó một mình.
Dưới đây là một số nguyên tắc tốt nhất để áp dụng khi ghi lại mã Go của bạn:
- Giữ cho tài liệu của bạn đơn giản và ngắn gọn.
- Bắt đầu câu khai báo hàm, kiểu và biến bằng tên của chúng.
- Bắt đầu một dòng bằng thụt lề để định dạng trước nó dưới dạng mã.
- Các nhận xét bắt đầu bằng “BUG (tên)” như “BUG (joe): Điều này không hoạt động” là đặc biệt. Godoc sẽ nhận ra chúng là lỗi và báo cáo chúng trong phần riêng của tài liệu.
Godoc có thể giúp bạn giải quyết vấn đề về tài liệu của mình
Sử dụng Godoc, bạn có thể làm việc hiệu quả hơn và bớt lo lắng về nỗ lực ghi chép các chương trình của bạn bằng tay.
Bạn nên giữ cho tài liệu của mình chính xác, chi tiết và đúng trọng tâm để khán giả mục tiêu của bạn dễ đọc và hiểu hơn. Điều quan trọng nữa là bạn phải cập nhật các nhận xét về mã khi bạn sửa đổi chương trình của mình.
Kiểm tra tài liệu gói Godoc để tìm hiểu thêm về cách sử dụng Godoc.