github.com/fluhus/godoc-tricks ↑

godoctricks package

import godoctricks "github.com/fluhus/godoc-tricks"

Package godoctricks is a tutorial on the features of GoDoc. It is meant to help eveyone make the most out of this feature of Go.

Notice that this doc is written in godoc itself as package documentation. The defined types are just for making the table of contents at the head of the page; they have no meanings as actual types.

If you have any suggestion or comment, please feel free to open an issue.

By Amit Lavon.

Update: Go 1.19 is here!

The new version introduces a few additions to what the godoc tool can recognize. You can see them below at Links, Headings and Lists. The official documentation is at: https://go.dev/doc/comment

Example

This function is named Example(), which is a package level test function.

❖ 
fmt.Println("Hello")
Example (other)

This function is named Example_other(), which is a package level test function and has the label "other".

❖ 
fmt.Println("Hello")
Example (wholeFilePackage)

A whole file example is a file that ends in `_test.go` and contains exactly one example function, no test or benchmark functions, and at least one other package-level declaration. 

package main

import "fmt"

var message = "Hello"

// A whole file example is a file that ends in `_test.go` and contains exactly one
// example function, no test or benchmark functions, and at least one other
// package-level declaration.
func main() {
	fmt.Println(message)
}

Output:

Hello

Index

Examples

func FuncExampleWithoutType

❖ 
func FuncExampleWithoutType() int

FuncExampleWithoutType is a func with an associated example (but not associated type). See Examples regarding the details.

Example

This function is named ExampleFuncExampleWithoutType(), this way godoc knows to associate it with the FuncExampleWithoutType func.

❖ 
fmt.Println("Hello", FuncExampleWithoutType())

type Bugs

❖ 
type Bugs doc.Note

You can use words other than "BUG", like "TODO". General syntax: MARKER(uid), with MARKER at least 2 chars (all caps) and uid at least 1 char.

By default, only BUG notes are shown. If you run a godoc server locally, you can control that with the -notes argument. For example, -notes="BUG|TODO".

type CodeBlocks

❖ 
type CodeBlocks int

You can embed blocks of code in your godoc, such as this: 

fmt.Println("Hello")

To do that, simply add an extra indent to your comment's text.

For example, the code of the first lines of this section looks like this: 

// You can embed blocks of code in your godoc, such as this:
//  fmt.Println("Hello")
// To do that, simply add an extra indent to your comment's text.

type Enums

❖ 
type Enums int

While there are no built in enums in go, you can use types and constants to make enum lookalikes (documentation-wise). Take this Enums type for example; if you have a const/var clause where all the values are of the same type, it will be attached to that type's godoc. See below.

❖ 
const (
	A Enums = iota
	B
)

type Examples

❖ 
type Examples int

You can place usage examples in your godoc.

Examples should be placed in a file with a _test suffix. For example, the examples in this guide are in a file called doc_test.go .

The example functions should be called Example() for package examples, ExampleTypename() for a specific type or ExampleFuncname() for a specific function, ExampleTypename_Methodname() for a method on a specific type.

For multiple examples for the same entity (like same function), you can add a suffix starting with a lowercase like ExampleFoo_suffix1, ExampleFoo_suffix2.

You can document an example's output, by adding an output comment at its end. The output comment must begin with "Output:", as shown below: 

func ExampleExamples_output() {
    fmt.Println("Hello")
    // Output: Hello
}

Notice that the tricks brought here (headings, code blocks, links etc.) don't work in example documentation.

For full documentation of examples, see: http://golang.org/pkg/testing/

Example

This function is named ExampleExamples(), this way godoc knows to associate it with the Examples type.

❖ 
fmt.Println("Hello")
Example (other)

This function is named ExampleExamples_other(), it is associated with Examples type and has the label "Other".

❖ 
fmt.Println("Hello")
Example (output)

This is how godoc parsed ExampleExamples_output() that was shown above.

❖ 
fmt.Println("Hello")
// Output: Hello
Example (wholeFileType)

A whole file example can also be attached to a given type (Examples here) with appropriate naming.

A whole file example is a file that ends in `_test.go` and contains exactly one example function, no test or benchmark functions, and at least one other package-level declaration. 

package main

import "fmt"

var messageExample = "Hello"

// A whole file example can also be attached to a given type (Examples here)
// with appropriate naming.
//
// A whole file example is a file that ends in `_test.go` and contains exactly one
// example function, no test or benchmark functions, and at least one other
// package-level declaration.
func main() {
	fmt.Println(messageExample)
}

func NewExamples

❖ 
func NewExamples() Examples

NewExamples is a func with an associated example. See Examples regarding the details.

Example

This function is named ExampleNewExamples(), this way godoc knows to associate it with the NewExamples func.

❖ 
fmt.Println("Hello", NewExamples())

func (Examples) ExampleMethod

❖ 
func (e Examples) ExampleMethod() int

ExampleMethod is a method with an associated example. See Examples regarding the details.

Example

This function is named ExampleExamples_ExampleMethod(), this way godoc knows to associate it with the ExampleMethod method of the Examples type.

❖ 
e := Examples(42)
fmt.Println("Hello", e.ExampleMethod())

type Github

❖ 
type Github int

Go code that you upload to public repositories on github appears automatically on the godoc website. Just like this tutorial! Just check in your code and watch as it appears. Use this page's URL as reference.

The godoc page gets updated once you make a new release.

type Headings

❖ 
type Headings int

You can make headings in your godoc. An explicit heading line starts with a '#' and is separated from the previous and next paragraphs with empty comment lines. An implicit heading is the same without the '#' (`go fmt` will automatically add a leading #). It needs to begin with a capital letter and not end with punctuation.

See the full documentation here: https://go.dev/doc/comment#headings

For example, this code: 

// # Explicit Heading
//
// Yada yada.
//
// Implicit Heading
//
// Yolo yolo.

Results in:

Explicit Heading

Yada yada.

Implicit Heading

Yolo yolo.

type Interface

❖ 
type Interface interface {
	Method()
}

Interface are rendered like Struct:

❖ 
type Links int

There are several ways to embed links in godoc.

Regular URLs

Web addresses will automatically generate links in the HTML output, like this: http://www.golang.org

You can link to identifiers in the documentation with square brackets.

Lines of the form "[something]: URL" turn the occurrences of [something] into links to that URL with the text "something". Lines of that form need to be separated from regular text with empty doc lines.

For example: 

You can search for Go [online].
See our [Links] section or [Methods.Foo].
Go to the imported [doc] package or the [doc.Note] struct.
Visit us under [github.com/fluhus/godoc-tricks.Links]

[online]: https://duckduckgo.com/?q=golang

Results in:

You can search for Go online. See our Links section or Methods.Foo. Go to the imported doc package or the doc.Note struct. Visit us under github.com/fluhus/godoc-tricks.Links.

type Lists

❖ 
type Lists int

Indented lines that start with dashes, stars, or pluses (or other unicode characters) create lists.

For example: 

This is my list
 - item 1
 - item 2

Results in:

This is my list

type LocalServer

❖ 
type LocalServer int

You can run a local godoc server. This is helpful for previewing documentation, or for cases where you don't have a stable internet connection. 

go run golang.org/x/tools/cmd/godoc@latest

godoc will listen on http://localhost:6060. Run with -h to see how you can control the port number and other options.

type Methods

❖ 
type Methods int

Methods are functions with receivers. Godoc associates methods with their receivers and attaches their documentation. See below.

func NewMethods

❖ 
func NewMethods() *Methods

Functions that construct an instance of a type (or a pointer to it) are associated with the returned type.

func (Methods) Foo

❖ 
func (Methods) Foo()

Methods are attached to their receiver type in the godoc, regardless of their physical location in the code.

func (*Methods) Foo2

❖ 
func (*Methods) Foo2()

Pointer receivers are also associated in the same way.

type Paragraphs

❖ 
type Paragraphs int

To start a new paragraph, add an empty line in the comment between the 2 paragraphs.

For example: 

// Paragraph 1.
// Still paragraph 1.
//
// Paragraph 2.
// Still Paragraph 2.

Results in:

Paragraph 1. Still paragraph 1.

Paragraph 2. Still Paragraph 2.

type Struct

❖ 
type Struct struct {
	// ExportedField can have a comment on the line above.
	ExportedField       int
	OtherExportedField  Links // or on the same line
	FieldWithoutComment struct{}
	// contains filtered or unexported fields
}

Struct will be shown with their exported fields. Unexported fields will be hidden under a comment "contains filtered or unexported fields". For instance the following struct 

type Struct struct {
	// ExportedField can have a comment on the line above.
	ExportedField       int
	OtherExportedField  Links // or on the same line
	FieldWithoutComment struct{}

	hidden int // unexported fields (and their comments) will not be shown in the documentation
}

will be rendered as:

Bugs

⚠ This is an example bug. See the [Bugs] section.

Source Files

doc.go

Forge

https://github.com/fluhus/godoc-tricks

git clone 
https://github.com/fluhus/godoc-tricks.git
git@github.com:fluhus/godoc-tricks.git
github.com/fluhus/godoc-tricks
v1.5.0