rpc: documentation basics

packages/go-kosu/rpc/doc.go

@@ -0,0 +1,5 @@
+// nolint
+
+/*
+ */
+package rpc

packages/go-kosu/rpc/doctool/main.go

@@ -1,13 +1,13 @@
 package main
 
 import (
-	"encoding/json"
 	"fmt"
 	"go/doc"
 	"go/parser"
 	"go/token"
 	"log"
 	"os"
+	"text/template"
 )
 
 // nolint
@@ -16,6 +16,18 @@ type DocEntry struct {
 	Text   string `json:"text"`
 }
 
+type TypeDocs struct {
+	Title       string
+	Description string
+	Entries     []DocEntry
+}
+
+type PkgDocs struct {
+	Title       string
+	Description string
+	Types       []TypeDocs
+}
+
 func main() {
 	if len(os.Args) < 2 {
 		fmt.Println("Usage: doctool <path>")
@@ -28,18 +40,28 @@ func main() {
 		log.Fatal(err)
 	}
 
-	docs := []DocEntry{}
 	pkg := doc.New(pkgs["rpc"], os.Args[1], doc.AllDecls)
+	pkgDocs := PkgDocs{
+		Title:       pkg.Name,
+		Description: pkg.Doc,
+	}
 	for _, t := range pkg.Types {
+		if t.Name != "Service" {
+			continue
+		}
+		typeDocs := TypeDocs{Title: t.Name, Description: t.Doc}
 		for _, m := range t.Methods {
-			docs = append(docs, DocEntry{Method: m.Name, Text: m.Doc})
+			typeDocs.Entries = append(typeDocs.Entries, DocEntry{Method: m.Name, Text: m.Doc})
 		}
+		pkgDocs.Types = append(pkgDocs.Types, typeDocs)
 	}
 
-	text, err := json.MarshalIndent(docs, "", "    ")
+	t, err := template.New("template.md").ParseFiles("./template.md")
 	if err != nil {
-		log.Fatal(err)
+		panic(err)
+	}
+	if err := t.Execute(os.Stdout, pkgDocs); err != nil {
+		panic(err)
 	}
 
-	fmt.Printf("%s\n", text)
 }

packages/go-kosu/rpc/doctool/template.md

@@ -0,0 +1,12 @@
+---
+title: Methods
+---
+
+{{ .Description }}
+
+{{- range .Types }}
+  {{- range .Entries }}
+## Method: {{ .Method }}
+{{ .Text }}
+  {{ end }}
+{{ end }}

packages/go-kosu/rpc/rpc_test.go

@@ -10,19 +10,25 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"go-kosu/abci"
+	"go-kosu/abci/types"
 	"go-kosu/tests"
 
 	"github.com/tendermint/tendermint/libs/db"
 )
 
-func TestRPCLatestHeight(t *testing.T) {
-	_, closer := tests.StartServer(t, db.NewMemDB())
-	defer closer()
+func setupNewTestClient(t *testing.T) (*abci.App, *rpc.Client, func()) {
+	app, closer := tests.StartServer(t, db.NewMemDB())
 	client := rpc.DialInProc(
 		NewServer(
 			abci.NewHTTPClient("http://localhost:26657", nil),
 		),
 	)
+	return app, client, closer
+}
+
+func TestRPCLatestHeight(t *testing.T) {
+	_, client, closer := setupNewTestClient(t)
+	defer closer()
 
 	var latest uint64
 	// Get the initial (prior the first block is mined)
@@ -34,6 +40,7 @@ func TestRPCLatestHeight(t *testing.T) {
 		// this is invoked when a block is mined
 		require.NoError(t, client.Call(&latest, "kosu_latestHeight"))
 		assert.EqualValues(t, 1, latest)
+
 		cancel()
 	}
 
@@ -55,3 +62,31 @@ func TestRPCLatestHeight(t *testing.T) {
 		}
 	}
 }
+
+func TestQueryPoster(t *testing.T) {
+	app, client, closer := setupNewTestClient(t)
+	defer closer()
+
+	poster := &types.Poster{
+		Limit: 99,
+	}
+	app.Store().SetPoster("abc", *poster)
+	app.Store().Commit()
+
+	t.Run("Found", func(t *testing.T) {
+		var res types.Poster
+		require.NoError(t,
+			client.Call(&res, "kosu_queryPoster", "abc"),
+		)
+		assert.Equal(t, *poster, res)
+
+	})
+
+	t.Run("NotFound", func(t *testing.T) {
+		var res types.Poster
+		err := client.Call(&res, "kosu_queryPoster", "a-not-found-address")
+		require.NotNil(t, err)
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "not found")
+	})
+}

packages/go-kosu/rpc/service.go

@@ -3,7 +3,6 @@ package rpc
 import (
 	"context"
 	"go-kosu/abci"
-	"log"
 
 	"github.com/ethereum/go-ethereum/rpc"
 )
@@ -20,9 +19,44 @@ func NewService(abci *abci.Client) *Service {
 	}
 }
 
-// Subscribe subscribes to the ABCI events
-// To tell which events you want, you need to provide a query.
-// More information about query can be found here: https://tendermint.com/rpc/#subscribe
+/*
+Subscribe subscribes to the ABCI events.
+
+To tell which events you want, you need to provide a query.
+More information about query can be found here: https://tendermint.com/rpc/#subscribe
+Subscriptions will only work over WS.
+#### Parameters
+`query` TM query string
+
+#### Returns
+`*rpc.Subscription`
+
+#### Examples
+```go
+ch := make(chan interface{})
+args := []interface{}{
+	"subscribe",
+	"tm.event='NewBlock'",
+}
+ctx := context.Background()
+sub, err := client.Subscribe(ctx, "kosu", ch, args...)
+if err != nil {
+	panic(err)
+}
+defer sub.Unsubscribe()
+
+for {
+	select {
+	case <-ctx.Done():
+		return
+	case <-sub.Err():
+		return
+	case e := <-ch:
+		fmt.Printf("event: %+v", e)
+	}
+}
+```
+*/
 func (s *Service) Subscribe(ctx context.Context, query string) (*rpc.Subscription, error) {
 	notifier, supported := rpc.NotifierFromContext(ctx)
 	if !supported {
@@ -56,8 +90,22 @@ func (s *Service) Subscribe(ctx context.Context, query string) (*rpc.Subscriptio
 	return rpcSub, nil
 }
 
-// LatestHeight returns the height of the best known block
-// The `latestHeight` method will return the integer height of the latest block committed to the blockchain.",
+/*
+LatestHeight returns the height of the best known block.
+The `latestHeight` method will return the integer height of the latest block committed to the blockchain.
+
+#### Parameters
+None
+
+#### Returns
+`latestHeight` - _int64_ latest block height
+
+#### Examples
+```bash
+curl -X POST --data '{"jsonrpc":"2.0","method":"kosu_latestHeight", "id": 1}' localhost:14341 --header 'Content-Type: application/json'
+{"jsonrpc":"2.0","id":1,"result":260}
+```
+*/
 func (s *Service) LatestHeight() (int64, error) {
 	res, err := s.abci.Block(nil)
 	if err != nil {