Mostly undocumented

[hsanjuan]

Going https://godoc.org/github.com/libp2p/go-libp2p-pubsub shows almost no documentation for any of the very numerous exported methods from this library. Golint shows 66 issues on this regard. Most existing documentation strings do not finish with a . so it looks ugly.

IMHO this gives a very bad image about the state of this code and in the end it counts towards people choosing to implement their own things rather than using libp2p, even though this library is amazing and works very well. I should not have to read the implementation to figure out how a pubsub subscription works, if Next() blocks or what it's actually happening.

The README is also sparse, without a link to godocs, without a CI badge, with no mention of Gx, and defines the library as "work in progress" when the reality is that it is very much a working piece of code heavily used in the IPFS ecosystem.

tl;dr: Please, maintainers, document your awesome code.

[whyrusleeping]

I think some godoc example code blocks would be really great. https://golang.org/pkg/testing/#hdr-Examples