godoctricks

package module
Version: v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 5, 2021 License: MIT Imports: 0 Imported by: 0

README

godoc-tricks

Go Reference

This is a guide on the features of GoDoc, to help everyone make the most out of this feature of Go.

Documentation

Overview

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 on this tutorial's GitHub page!

By Amit Lavon

Example

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

package main

import (
	"fmt"
)

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

Example (Other)

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

package main

import (
	"fmt"
)

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

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Bugs added in v1.1.0

type Bugs int

You can mention bugs in the documentation. The syntax for that is like so:

// BUG(username): Some information.
// Some more information.

This creates a section for bugs where each bug block is shown. You can use words other than "BUG", like "TODO". 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 added in v1.1.0

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 added in v1.3.0

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 = 1
	B Enums = 2
)

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. For multiple examples for the same entity (like same function), you can add a suffix 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 (titles, 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.

package main

import (
	"fmt"
)

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

Example (Other)

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

package main

import (
	"fmt"
)

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

Example (Output)

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

package main

import (
	"fmt"
)

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

Hello

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 Links int

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

type LocalServer added in v1.1.0

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.

First you need to get the godoc tool:

go get golang.org/x/tools/cmd/godoc

Then simply running godoc will make it 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.

yields:

Paragraph 1. Still paragraph 1.

Paragraph 2. Still Paragraph 2.

type Titles

type Titles int

You can make titles in your godoc. A title is a line that is separated from its following line by an empty line, begins with a capital letter and doesn't end with punctuation.

For example, the code:

// Sentence 1
//
// Sentence 2

yields:

Sentence 1

Sentence 2

While this code:

// Sentence 1.
//
// Sentence 2.

yields:

Sentence 1.

Sentence 2.

See documentation here: http://golang.org/pkg/go/doc/#ToHTML

Notes

Bugs

  • This is an example bug. See the bugs section.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL