testdoc

README

go-testdoc

go-testdoc runs your code documentation examples during normal test time.

go get -u github.com/Eun/go-testdoc

Example

This example will run the go code inside the Example and Examples section using yaegi.

// example.go file
package example

// IsLoggedIn returns true if the current user has access to the service.
//
// Example:
//     if IsLoggedIn() {
//         fmt.Println("You are logged in")
//     }
func IsLoggedIn() bool {
	return true
}

// CurrentUser returns the current username of the logged in user.
//
// Examples:
//     fmt.Println(CurrentUser())
//
//     if IsLoggedIn() {
//         fmt.Println(CurrentUser())
//     }
func CurrentUser() string {
	return "Joe Doe"
}

// example_test.go file
package example_test

import (
	"testing"

	"github.com/Eun/go-testdoc"
)

func TestDocumentation(t *testing.T) {
	testdoc.TestCodeDocumentation(t, &testdoc.Options{
		// Test for this folder
		Path: ".",

		// Test the `example` package
		PkgName: "example",

		// Execute code inside the `Example` and `Examples` sections
		Sections: []string{"Example", "Examples"},

		Imports: []testdoc.Import{
			// Import some standard packages we need
			{Name: "", Path: "fmt"},

			// Import the current package so we can call the functions.
			{Name: ".", Path: "./"},
		},
	})
}

See also

Testing your README.md file

Documentation

Overview

Package testdoc allows you to test your code your code documentation examples during normal test time.

Index

• func TestCodeDocumentation(t interface{ ... }, options *Options)
• type Doc
  • func ParseDoc(s string) (*Doc, error)
• type Import
• type Options

Functions

func TestCodeDocumentation

func TestCodeDocumentation(t interface {
	Fatalf(string, ...interface{})
	Fatal(...interface{})
}, options *Options)

TestCodeDocumentation can be used to test documentation for functions, structs, interfaces...

Types

type Doc

type Doc struct {
	Description string
	Fields      map[string]string
}

Doc represents an documentation block.

func ParseDoc

func ParseDoc(s string) (*Doc, error)

ParseDoc parses an documentation block and returns an instance to Doc. It will parse Sections separated by a colon and populate them in the Doc.Fields field. Example: Take following input: Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Field1:

Hello World

Field2:

Good Bye World

Will return

Doc{
   Description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
   Fields: map[string]string{
       "Field1": "Hello World",
       "Field2": "Good Bye World",
   },
}.

type Import

type Import yaegi_template.Import

Import represents an import that should be evaluated.

type Options

type Options struct {
	Path           string
	PkgName        string
	Sections       []string
	Symbols        []interp.Exports
	Options        *interp.Options
	Imports        []Import
	IncludePrivate bool
}

Options options for TestCodeDocumentation.