Page Content

Tutorials

What Is Mean By Documentation In Golang With Code Examples

Documentation in Golang

For creating and browsing documentation for Go programs and packages, the godoc utility is an effective tool. Even without an internet connection, developers may obtain thorough documentation for Go functions and packages that are already in place. You can use the godoc tool as a web server or as a command-line application.

How to Write Go Documentation

Comments in the source code are used to document Go packages and their contents. Go adheres to particular standards for these remarks:

Placement: A package, function, variable, or constant must have one or more regular comment lines beginning with // placed immediately before its declaration in order to be documented.

Exported Items: The generated documentation will only include “exported” elements (those that begin with a capital letter) that are visible outside of their package.

Package Comments: The comment that comes before the package declaration, which is the initial line of a package’s documentation, should be descriptive and will show up in the godoc package list.

Bug Reports: The package documentation’s “Bugs” section will have comments that start with BUG(something).

Omitted Comments: Comments that don’t come just before a top-level declaration are not included in the godoc output.

Best Practices: The utilization of a package and the peculiarities of its functions are made clear by good documentation. Documenting the “why” behind the code is preferable to just the “what” or “how,” unless the code is really complicated. Avoid over-commenting unless you are trying to reach a specific audience, and assume that other programmers understand Go.

Example of Documentation Comments

// This package is for showcasing the documentation capabilities of Go
// It is a naive package!
package documentMe
// Pie is a global variable
// This is a silly comment!
const Pie = 3.1415912
// The S1() function finds the length of a string
// It iterates over the string using range
func S1(s string) int {
    if s == "" {
        return 0
    }
    n := 0
    for range s {
        n++
    }
    return n
}
// The F1() function returns the double value of its input integer
// A better function name would have been Double()!
func F1(n int) int {
    return 2 * n
}

Output

// This package is for showcasing the documentation capabilities of Go
// It is a naive package!
package documentMe
// Pie is a global variable
// This is a silly comment!
const Pie = 3.1415912
// The S1() function finds the length of a string
// It iterates over the string using range
func S1(s string) int {
	if s == "" {
		return 0
	}
	n := 0
	for range s {
		n++
	}
	return n
}
// The F1() function returns the double value of its input integer
// A better function name would have been Double()!
func F1(n int) int {
	return 2 * n
}

Using the Tool

There are two main ways that the godoc tool might be utilized:

Command-Line Application: Documentation for individual functions or complete packages can be viewed directly in your terminal.

  • To view documentation for a specific function, for example, Println from the fmt package, you would type: godoc fmt Println This command would display details such as: 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.
  • Godoc cmd/fmt can be used to examine documentation for a package as a whole, such as the fmt package itself.
  • The complete import path for bespoke packages should be used. To inspect the Average function in a custom math package.

Web Server: Godoc has the ability to start a local web server, which lets you use a web browser to view all installed Go packages and their documentation.

  • Use the command godoc -http=”:6060″ to launch the godoc web server on port 60601.
  • After that, you may open the documentation by navigating to http://localhost:6060/pkg/ in your browser. All packages and their features, including the comments you’ve provided for documentation, can be seen through this interface.

Integration with Example Functions

Additionally, godoc incorporates “example functions,” which function as executable tests and documentation.

Definition: In _test, example functions are defined.Start with Example by going to the files. They don’t accept parameters and don’t give back any values.

Verification: The go test command will run an example function with a // Output: remark to see if the actual output matches the intended output mentioned in the comment.

Documentation Display: These sample functions are automatically shown in the godoc manual for the corresponding package or function, together with their code and validated output.

Example of an Example Function:

package documentMe
import (
    "fmt"
)
func ExampleS1() {
    fmt.Println(S1("123456789"))
    fmt.Println(S1(""))
    
}

Output

9
0

The output will be checked against the // Output: lines when the go test runs this example function for S1(). If consistent, when examined through godoc, it will appear as part of the documentation for S1().

You can also read What Is Mean By Profiling In Go With Code Examples

Agarapu Geetha
Agarapu Geetha
My name is Agarapu Geetha, a B.Com graduate with a strong passion for technology and innovation. I work as a content writer at Govindhtech, where I dedicate myself to exploring and publishing the latest updates in the world of tech.
Index