MM-11292: clean up plugins GoDoc (#9109)

* clean up plugins GoDoc:

- eliminate plugin.NewBlankContext() as unnecessary
- export ValidIdRegex as a string vs. the less readable var
- add/update various documentation strings
- hide everything by default, except where used by client plugins or the mattermost-server. The exception to this rule are the `*(Args|Returns)` structs which must be public for go-plugin, but are now prefixed with `Z_` with a warning not to use.
- include a top-level example to get plugin authors started

This is not a breaking change for existing plugins compiled against
plugins-v2.

* remove commented out ServeHTTPResponseWriter

* update examples to match developer docs

* add missing plugin/doc.go license header

plugin/client.go

@@ -7,8 +7,9 @@ import (
 	"github.com/hashicorp/go-plugin"
 )
 
-// Starts the serving of a Mattermost plugin over rpc or gRPC
-// Call this when your plugin is ready to start
+// Starts the serving of a Mattermost plugin over net/rpc. gRPC is not yet supported.
+//
+// Call this when your plugin is ready to start.
 func ClientMain(pluginImplementation interface{}) {
 	if impl, ok := pluginImplementation.(interface {
 		SetAPI(api API)
@@ -21,28 +22,39 @@ func ClientMain(pluginImplementation interface{}) {
 	}
 
 	pluginMap := map[string]plugin.Plugin{
-		"hooks": &HooksPlugin{hooks: pluginImplementation},
+		"hooks": &hooksPlugin{hooks: pluginImplementation},
 	}
 
 	plugin.Serve(&plugin.ServeConfig{
-		HandshakeConfig: Handshake,
+		HandshakeConfig: handshake,
 		Plugins:         pluginMap,
 	})
 }
 
 type MattermostPlugin struct {
-	API     API
+	// API exposes the plugin api, and becomes available just prior to the OnActive hook.
+	API API
+
 	selfRef interface{} // This is so we can unmarshal into our parent
 }
 
+// SetAPI persists the given API interface to the plugin. It is invoked just prior to the
+// OnActivate hook, exposing the API for use by the plugin.
 func (p *MattermostPlugin) SetAPI(api API) {
 	p.API = api
 }
 
+// SetSelfRef is called by ClientMain to maintain a pointer to the plugin interface originally
+// registered. This allows for the default implementation of OnConfigurationChange.
 func (p *MattermostPlugin) SetSelfRef(ref interface{}) {
 	p.selfRef = ref
 }
 
+// OnConfigurationChange provides a default implementation of this hook event that unmarshals the
+// plugin configuration directly onto the plugin struct.
+//
+// Feel free to implement your own version of OnConfigurationChange if you need more advanced
+// configuration handling.
 func (p *MattermostPlugin) OnConfigurationChange() error {
 	if p.selfRef != nil {
 		return p.API.LoadPluginConfiguration(p.selfRef)