Add documentation for plugin HTTP APIs

[wfarner]

I hope to have API docs generated automatically at some point, but for now here is a draft of docs with a tool to mitigate drift.

Closes #305

[wfarner]

Looks like the build is broken on master. For posterity, here's the stack trace:

2016/11/29 23:55:22 http: panic serving @: Fail in goroutine after TestNoCallsToGroupWhenNoLeader has completed
goroutine 49 [running]:
net/http.(*conn).serve.func1(0xc420095f80)
	/usr/local/go/src/net/http/server.go:1491 +0x15c
panic(0x859460, 0xc420110df0)
	/usr/local/go/src/runtime/panic.go:458 +0x271
testing.(*common).Fail(0xc42008cd80)
	/usr/local/go/src/testing/testing.go:412 +0x182
testing.(*common).FailNow(0xc42008cd80)
	/usr/local/go/src/testing/testing.go:431 +0x39
testing.(*common).Fatalf(0xc42008cd80, 0x8df421, 0x24, 0xc42010bb60, 0x3, 0x3)
	/usr/local/go/src/testing/testing.go:496 +0x95
testing.(*T).Fatalf(0xc42008cd80, 0x8df421, 0x24, 0xc42010bb60, 0x3, 0x3)
	<autogenerated>:12 +0x87
github.com/docker/infrakit/vendor/github.com/golang/mock/gomock.(*Controller).Call(0xc4200d6720, 0x897540, 0xc42006b660, 0x8d643b, 0xd, 0x0, 0x0, 0x0, 0x0, 0x0, ...)
	/home/ubuntu/.go_workspace/src/github.com/docker/infrakit/vendor/github.com/golang/mock/gomock/controller.go:113 +0x5d4
github.com/docker/infrakit/pkg/mock/spi/group.(*MockPlugin).InspectGroups(0xc42006b660, 0x8475d7, 0x8475c0, 0x1, 0xace540, 0x466682)
	/home/ubuntu/.go_workspace/src/github.com/docker/infrakit/pkg/mock/spi/group/group.go:75 +0xa9
github.com/docker/infrakit/pkg/rpc/group.(*Group).InspectGroups(0xc42006b670, 0xc4200dcc30, 0xaea008, 0xc42012c900, 0x0, 0x0)
	/home/ubuntu/.go_workspace/src/github.com/docker/infrakit/pkg/rpc/group/service.go:60 +0x56
reflect.Value.call(0xc420094800, 0xc42007e108, 0x13, 0x8d36fe, 0x4, 0xc420127a18, 0x4, 0x4, 0xc4200dcc30, 0xc42012c900, ...)
	/usr/local/go/src/reflect/value.go:434 +0x6d6
reflect.Value.Call(0xc420094800, 0xc42007e108, 0x13, 0xc420127a18, 0x4, 0x4, 0x0, 0x415dcf, 0xc41fffcb0a)
	/usr/local/go/src/reflect/value.go:302 +0xc1
github.com/docker/infrakit/vendor/github.com/gorilla/rpc/v2.(*Server).ServeHTTP(0xc42006b690, 0xaadc00, 0xc420069e80, 0xc4200dcc30)
	/home/ubuntu/.go_workspace/src/github.com/docker/infrakit/vendor/github.com/gorilla/rpc/v2/server.go:142 +0x741
github.com/docker/infrakit/pkg/rpc/server.loggingHandler.ServeHTTP(0xaa9080, 0xc42006b690, 0xaadbc0, 0xc4200ebad0, 0xc4200dcc30)
	/home/ubuntu/.go_workspace/src/github.com/docker/infrakit/pkg/rpc/server/server.go:49 +0x280
github.com/docker/infrakit/pkg/rpc/server.(*loggingHandler).ServeHTTP(0xc42006b720, 0xaadbc0, 0xc4200ebad0, 0xc4200dcc30)
	<autogenerated>:1 +0x9e
net/http.serverHandler.ServeHTTP(0xc420094e00, 0xaadbc0, 0xc4200ebad0, 0xc4200dcc30)
	/usr/local/go/src/net/http/server.go:2202 +0xbc
net/http.(*conn).serve(0xc420095f80, 0xaae300, 0xc420069d40)
	/usr/local/go/src/net/http/server.go:1579 +0x5f7
created by net/http.(*Server).Serve
	/usr/local/go/src/net/http/server.go:2293 +0x541

[codecov-io]

Current coverage is 68.97% (diff: 100%)

Merging #311 into master will increase coverage by 15.00%

@@             master       #311   diff @@
==========================================
  Files            10         27     +17   
  Lines           428       1441   +1013   
  Methods           0          0           
  Messages          0          0           
  Branches          0          0           
==========================================
+ Hits            231        994    +763   
- Misses          164        355    +191   
- Partials         33         92     +59   

Powered by Codecov. Last update a6d51a5...263de0b

[chungers]

LGTM

[chungers]

Looks like the panic is from gomock. I will see about adding a expect/anytimes call expectation to see if that helps. There's something with the way the test shuts down and somehow the leader detection for the leader sees a negative edge (leader -> not leader) and some unexpected call were made to unwatch/free the groups.