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, 10 insertions, 7 deletions

diff --git a/plugin/hooks.go b/plugin/hooks.go
index daeffbc32..5200291f2 100644
--- a/plugin/hooks.go
+++ b/plugin/hooks.go
@@ -9,8 +9,10 @@ import (
 	"github.com/mattermost/mattermost-server/model"
 )
 
-// These assignments are part of the wire protocol. You can add more, but should not change existing
-// assignments. Follow the naming convention of <HookName>Id as the autogenerated glue code depends on that.
+// These assignments are part of the wire protocol used to trigger hook events in plugins.
+//
+// Feel free to add more, but do not change existing assignments. Follow the naming convention of
+// <HookName>Id as the autogenerated glue code depends on that.
 const (
 	OnActivateId            = 0
 	OnDeactivateId          = 1
@@ -29,15 +31,16 @@ const (
 	TotalHooksId            = iota
 )
 
-// Methods from the Hooks interface can be used by a plugin to respond to events. Methods are likely
-// to be added over time, and plugins are not expected to implement all of them. Instead, plugins
-// are expected to implement a subset of them and pass an instance to plugin/rpcplugin.Main, which
-// will take over execution of the process and add default behaviors for missing hooks.
+// Hooks describes the methods a plugin may implement to automatically receive the corresponding
+// event.
+//
+// A plugin only need implement the hooks it cares about. The MattermostPlugin provides some
+// default implementations for convenience but may be overridden.
 type Hooks interface {
 	// OnActivate is invoked when the plugin is activated.
 	OnActivate() error
 
-	// Implemented returns a list of hooks that are implmented by the plugin.
+	// Implemented returns a list of hooks that are implemented by the plugin.
 	// Plugins do not need to provide an implementation. Any given will be ignored.
 	Implemented() ([]string, error)