kubernetes: SharedInformer documentation is missing or hard to find

Is this a BUG REPORT or FEATURE REQUEST?: /kind bug

What happened: I cannot find documentation on the correct way to use informers & shared informers. Without guidance, I ended up writing code that called "k8s.io/client-go/informers/core/v1".NewPersistentVolumeInformer (and some others). Although I read the docstring of that method, it was only through conversation with a more experienced contributor that I learned I should instead be calling "k8s.io/client-go/informers".(*sharedInformerFactory).Core().V1().PersistentVolumes().Informer()

I also had difficulty understanding whether I needed to call Run() on each informer, or on the informer factory. The correct answer turns out to be "k8s.io/client-go/informers".(*sharedInformerFactory).Start() but that was not apparent from the godoc as Start() comes from an embedded interface which I didn’t notice.

EDIT: Calling Start() before creating informers in the factory results in those informers never generating events. I suppose this means that one should never call Start() until all informers have been created? Not sure.

What you expected to happen: There should be a doc somewhere that says, “To use a shared informer, make a factory and call Start() on it.” and that doc should be easy to find.

/sig api-machinery