How to document Golang functions for the public?

Best practices for writing Golang function documentation include: using the godoc tool to automatically generate documentation. Write clear function signatures that describe input, output, and return types. Use detailed comments to explain the function's purpose, how it works, and how to use it. Provide code examples that show how the function is used. Test the generated documentation with godoc -http=:8080.

How to write public-facing Golang function documentation

Writing excellent Golang function documentation is scalable and user-friendly for building and maintaining software is crucial. Following the following best practices can help you create public-facing and easy-to-understand documentation:

1. Use godoc

Using the official godoc tool is the recommendation for generating Golang function documentation Way. It automatically generates markup using function signatures, comments, and sample code. Just add the following comment before the function definition:

// 函数使用方法
//
// 示例1：
//    _, err := doSomething(1, 2)
// 示例2：
//    fmt.Println(doSomething(3, 4))
func doSomething(i, j int) (string, error)

2. Write a clear function signature

The function signature should accurately describe the input, output, and return types of the function:

// 返回一个包含 slice 中所有奇数的 slice
func oddNumbers(slice []int) []int

3. Use clear and detailed comments

Comments should explain what the purpose of the function is, how it works, and how to use it. Avoid using technical jargon or ambiguous language:

// 计算一个字符串中每个字符出现的次数。
//
// 字符串区分大小写。
func CountChars(str string) map[rune]int

4. Provide code examples

Including code examples in comments allows users to quickly understand how a function is used. Make sure the examples cover common and edge use cases:

// 示例：
//
// str 为 "Hello"，返回 map[rune]int{"H": 1, "e": 1, "l": 2, "o": 1}
func CountChars(str string) map[rune]int

5. Test documentation

Rungodoc -http=:8080 and visit the generated documentation website to verify that the documentation is correct.

Practical case:

The following is an example of generating a function document:

// 根据给定的精度截断小数。
//
// 如果精度为 0，则返回一个整数。
// 如果精度为正数，则返回一个带指定小数位的浮点数。
// 如果精度为负数，则返回舍入到最接近整数的数。
//
// 示例1：
//    res := Truncate(3.14, 2)
//    fmt.Println(res) // 输出： 3.14
// 示例2：
//    res := Truncate(-5.5, 1)
//    fmt.Println(res) // 输出： -6
func Truncate(number float64, precision int) float64

The generated document can be found at http://localhost:8080/ View on pkg/.

The above is the detailed content of How to document Golang functions for the public?. For more information, please follow other related articles on the PHP Chinese website!