search

tendermint / coding

14 stars 10 forks source link

all: add a doc.go file for high level intro and dive for packages #27

Closed odeke-em closed 7 years ago

odeke-em commented 7 years ago

Raised offline, let's add a doc.go file to each package whenever we can, to share some high level intro into our packages. I highly believe this will improve developer productivity.

I got bit by the lack of context/familiarity with the libraries in https://github.com/tendermint/go-crypto/issues/35 which supersedes https://github.com/tendermint/go-crypto/pull/32 and https://github.com/tendermint/go-crypto/pull/31, in which I spent a bit of time extracting the code from the libraries yet actually it only required invoking GenEd25519Key().PubKey()

My offline exhibit was: If so, we can do such a thing as https://github.com/golang/go/blob/0202aa8ec79bf700732812624eedcec3e6e300ad/src/net/http/doc.go#L5-L107 which then gives the Overview at https://golang.org/pkg/net/http/ which gives

https://godoc.org/github.com/golang/go/src/net/http

melekes commented 7 years ago

I second that. Let's try to document packages better!