Charlie Parker
Charlie Parker

Reputation: 5169

Why doesn't godoc skip examples in golang?

I was trying to make a documentation and provide examples but I didn't understand how to because godoc was skipping my examples.

when I go to localhost:8080/pkg/hello_example on the browser it print on the terminal:

2014/07/01 15:54:29 skipping example 'ExampleAuthenticate' because 'Authenticate' is not a known function or type
2014/07/01 15:54:29 skipping example 'ExampleGetAllowAllDriver' because 'GetAllowAllDriver' is not a known function or type
2014/07/01 15:54:29 skipping example 'ExampleGetAndUseAllowAllDriver' because 'GetAndUseAllowAllDriver' is not a known function or type
2014/07/01 15:54:29 skipping example 'ExampleGetAndUseDenyAllDriver' because 'GetAndUseDenyAllDriver' is not a known function or type
2014/07/01 15:54:29 skipping example 'ExampleGetDenyAllDriver' because 'GetDenyAllDriver' is not a known function or type
2014/07/01 15:54:29 skipping example 'ExampleGetRedisDriver' because 'GetRedisDriver' is not a known function or type
2014/07/01 15:54:30 skipping example 'ExampleAuthenticate' because 'Authenticate' is not a known function or type
2014/07/01 15:54:30 skipping example 'ExampleGetAllowAllDriver' because 'GetAllowAllDriver' is not a known function or type
2014/07/01 15:54:30 skipping example 'ExampleGetAndUseAllowAllDriver' because 'GetAndUseAllowAllDriver' is not a known function or type
2014/07/01 15:54:30 skipping example 'ExampleGetAndUseDenyAllDriver' because 'GetAndUseDenyAllDriver' is not a known function or type
2014/07/01 15:54:30 skipping example 'ExampleGetDenyAllDriver' because 'GetDenyAllDriver' is not a known function or type
2014/07/01 15:54:30 skipping example 'ExampleGetRedisDriver' because 'GetRedisDriver' is not a known function or type
^C%

I don't understand, so I cannot make arbitrary names of examples? Do the names have to match function names of my package or of my file? This is in my test package, so I am probably trying to test function in a different package and file. How do I do this?

Upvotes: 0

Views: 1033

Answers (1)

creack
creack

Reputation: 121652

godoc is very picky regarding the names, your Example function name needs to correlate with an actual function name, type name or other. See http://golang.org/pkg/testing/#hdr-Examples for reference.

Example of godoc exmaple: https://godoc.org/github.com/creack/multio#example-Multiplexer--ReadWriter, code: https://github.com/creack/multio/blob/master/example_test.go

You will notice, that the Example are called ExampleMultiplexer_simple ExampleMultiplexer_readWriter. This is because I wanted two example, I could have simply use ExampleMultiplexer. This works because I have a type called (exactly) Multiplexer. If you have a function, you can do the same, but the name needs to match.

When using a suffixe, it is very important that the suffix begins with a lowercase, otherwise godoc will discard it.

So to answer your question: yes you can use arbitrary name, but you still need to follow the godoc style of ExampleTypeName_suffix (lower case suffix first letter)

Upvotes: 4

Related Questions