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

1 files changed, 3 insertions, 2 deletions

diff --git a/plugin/api.go b/plugin/api.go
index 2b15a3d09..76df9377a 100644
--- a/plugin/api.go
+++ b/plugin/api.go
@@ -11,7 +11,8 @@ import (
 // The API can be used to retrieve data or perform actions on behalf of the plugin. Most methods
 // have direct counterparts in the REST API and very similar behavior.
 //
-// Plugins can obtain access to the API by implementing the OnActivate hook.
+// Plugins obtain access to the API by embedding MattermostPlugin and accessing the API member
+// directly.
 type API interface {
 	// LoadPluginConfiguration loads the plugin's configuration. dest should be a pointer to a
 	// struct that the configuration JSON can be unmarshalled to.
@@ -178,7 +179,7 @@ type API interface {
 	LogWarn(msg string, keyValuePairs ...interface{})
 }
 
-var Handshake = plugin.HandshakeConfig{
+var handshake = plugin.HandshakeConfig{
 	ProtocolVersion:  1,
 	MagicCookieKey:   "MATTERMOST_PLUGIN",
 	MagicCookieValue: "Securely message teams, anywhere.",