sub

package
Version: v0.0.0-...-eb5b069 Latest Latest
Warning

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

Go to latest
Published: Jan 9, 2016 License: MIT Imports: 1 Imported by: 0

Documentation

Overview

Package sub contains the rest of the article.

This Text

In the files of a library package, you can attach a comment to the package name, which will be shown in the overview for that package's documentation. Just like for command documentation, the convention is to use a file called doc.go for your package documentation, though it is not necessary. If you have comments on the package name in multiple files, they'll be concatenated, but generally it's best to just have comments in one file.

Just as with the command documentation, the first sentence in the documentation is used as the short description of the code in the package index. By convention, it should start with the words "Package <packagename>".

Examples

One of the coolest things about godoc is that you can have code snippets embedded in your documentation that get run with go test. These are called examples, and they are specially named functions in test files (files that end in _test.go) that have their code automatically embedded in the documentation for a package, type, method, or function.

To write an example function on the package as a whole, simply put a function in a test file called func Example(). For functions and types, the function name should be ExampleName(), where Name is the name of the type or function. To make an example for a method on a type, the function name should be ExampleType_Method, where Type is the name of the type and Method is the name of the method on the type.

If you need more than one example for any of these, you can make additional functions with the same name, and a suffix of _sometext, where sometext is whatever lowercase text you want. The suffix will be shown in parentheses after the Example label.

What gets displayed

If the contents of a test file contain a single example function, code outside the example function, and no other test, example, or benchmark functions, the entire file will be used as the example. Traditionally, full file examples are placed in a file called example_test.go, though this is not required.

If you have multiple example functions in the same file or examples and other tests in the same file, only the actual example function and code internal to it will be displayed in the documentation (which can be handy if you want the example to be shorter).

Examples as tests

Examples aren't just for documentation, they're actual tests too. During a run of "go test", the code in an example is run. This makes sure your examples will always compile. In addition, if the example outputs to stdout, you can actually test the output, and have a failing test if the output doesn't match. To do this, simply put a comment at the end of the function, with the first line as "output:". Further lines will be stripped of their comment prefix, trimmed of whitespace, and matched against the example's output (line breaks in the comments match "\n" from the output of the example code).

In the code, examples look like this:

func ExampleFood() {
	f := sub.NewFood("apple")
	fmt.Println(f.Weight())
	// output:
	// 5
}

Runnable Examples

Some of your examples may be able to be run right from the documentation, using the same technology that http://play.golang.org uses (in fact, godoc.org's support for this actually sends you to play.golang.org). To see this on your local godoc, start godoc with the -play option. However, be aware that the use of this option is limited.

In order for an example to be runnable, it can only reference code in the same file as it, or code in the standard library. This ends up being quite limiting, because you can't actually use any of the types or functions written in your package.

Package example

The example below is a whole-file example, and shows how to embed an example in the package documentation. Expand the example to read more about whole file examples. Note that the example is placed here, because the name of the example function is "Example()", and thus is an example about the entire package.

Example

This text is the comment on the Example() function itself, and is displayed ahead of the actual example code in the documentation. Note that unlike docs elsewhere, docs on examples are plaintext only, so be brief.

package main

// This is the actual contents of example_test.go.

import (
	"fmt"
)

// This text is the comment on the Example() function itself, and is displayed
// ahead of the actual example code in the documentation.  Note that unlike docs
// elsewhere, docs on examples are plaintext only, so be brief.
func main() {
	hello()
}

// Because we have code external to the example, and no other test,  or
// example functions in the file, godoc uses the whole file as the example.
func hello() {
	fmt.Println("Hello example!")
}
Output:

Hello example!

Index

Examples

Constants

View Source
const (
	// PearName is an exported constant used to create pear foods. Docs on
	// constants and variables enclosed in a block like this one get printed out
	// as-is.
	PearName = "pear"

	// PineappleName is the name of a pineapple.
	PineappleName = "pineapple"
)

This text is a doc comment on the const block as a whole. Unlike the comments inside the block, this text has full formatting.

This can be a nice way to write a single comment about a group of variables.

View Source
const AppleName = "apple"

Constants are sorted to the top of the code documentation.

Formatting

Because it is declared on its own and not in a const() block, AppleName gets full formatting support.

Variables

Apple is a global variable in the package.

Because apple is declared on its own, rather in a block of var (), its documentation gets full formatting support.

View Source
var (
	// Pear is another global variable in the package.
	Pear = NewFood(PearName)
)

This is a block of variables with a formatted comment.

Pretty nice.

Functions

func Eat

func Eat(f Food)

Eat consumes the food and prints out a nice message.

This is an example of a function that isn't a "constructor" style function, so it will be sorted at the top level of the documentation.

Functions get sorted before types.

func Zap

func Zap(f Food)

Zap consumes the food and prints out a nasty message.

This is just another top level function to show how the alphabetical sorting works.

Types

type Food

type Food struct {
	// Name holds the common name of the food.
	//
	// Alas, no formatting here.
	Name string
	// contains filtered or unexported fields
}

Food is a type to show how type documentation works.

Formatting

You always get full formatting on type, function, and method docs.

Example

This is an example function for a type. This line comes from the comment on the example function. See how the code is is displayed and then the output? Note that the output is just printing what you put under the output: comment in the function. It's not actually running the code to get that output.

f := NewFood("apple")
fmt.Println(f.Weight())
Output:

5
var Favorite Food = Pear

Favorite is a global variable in the package.

Because it is declared with a type defined within the package, it is sorted with the type definition in the documentation.

Below is the auto-embedded example from the function ExampleFood in more_examples_test.go.

func NewFood

func NewFood(name string) Food

NewFood creates a new Food with the given name and a calculated weight.

Godoc sorts "constructor" style functions like this, that return a type defined in the package, under the type itself.

Note that you do not need to (and should not) make separate lines describing each parameter to the function. Simply refer to the parameters by their name when you need to reference them in the rest of the documentation.

Example

Example documentation on a function.

f := NewFood("pear")
fmt.Println(f.Name)
Output:

pear
Example (Aux)

Second example on the same function, the name of this example function is ExampleNewFood_aux.

f := NewFood("prickly pear")
fmt.Println(f.Name)
Output:

prickly pear

func (Food) Weight

func (f Food) Weight() int

Weight reports the weight of the food in letters.

When decribing a function without parameters that simply returns data, it is traditional to write the doc saying the function reports foo, rather than *returns* foo.

The example below intentionally fails during go test, to show you what that looks like. The test will report:

--- FAIL: ExampleFood_Weight (4.933us)
got:
9
want:
10
FAIL
exit status 1
Example

Example on a method, the name of this example function is ExampleFood_Weight. Note that if you run go test, this test will fail, because the output doesn't match the comment (the actual output is 9). Note that the docs still say the output is 10, because that's what the comment says in the code.

f := NewFood("pineapple")
fmt.Println(f.Weight())
Output:

10

type Weight

type Weight int

Weight is a type to show how type-associated const and var documentation works.

const (
	Small Weight = 1  // This much fruit is not enough.
	Big   Weight = 20 // This is way too much fruit.
)

Constant declarations are sorted with their type definition when all the constant types match.

This works with elided type definition using iota, but does not work when the constant type is deduced from the constant expression.

var WeightPreference Weight

Variable declarations of a specific type are also associated with their type declaration in the documentation.

Notes

Bugs

  • This is a bug description. Bugs are an exception to the rule about only attached comments getting displayed in godoc. Simply make a comment that starts with BUG(foo) where foo is the name of the person responsible for the bug, and it'll show up in the list of bugs in godoc. Note that bug descriptions are plaintext only. You can click on the link at the beginning of the bug description to go right to the place where the BUG comment is located in the code.

  • Note that bugs in the command (application) package do not show up on godoc.org. This appears to be a bug in godoc.org, as they do show up in local godoc.

Source Files

Directories

Path Synopsis
Package subsub wraps up the article.
Package subsub wraps up the article.

Jump to

Keyboard shortcuts

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