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, 12 insertions, 5 deletions

diff --git a/plugin/valid.go b/plugin/valid.go
index 62c594a1a..5c543e673 100644
--- a/plugin/valid.go
+++ b/plugin/valid.go
@@ -9,16 +9,23 @@ import (
 )
 
 const (
-	MinIdLength = 3
-	MaxIdLength = 190
+	MinIdLength  = 3
+	MaxIdLength  = 190
+	ValidIdRegex = `^[a-zA-Z0-9-_\.]+$`
 )
 
-var ValidId *regexp.Regexp
+// ValidId constrains the set of valid plugin identifiers:
+//  ^[a-zA-Z0-9-_\.]+
+var validId *regexp.Regexp
 
 func init() {
-	ValidId = regexp.MustCompile(`^[a-zA-Z0-9-_\.]+$`)
+	validId = regexp.MustCompile(ValidIdRegex)
 }
 
+// IsValidId verifies that the plugin id has a minimum length of 3, maximum length of 190, and
+// contains only alphanumeric characters, dashes, underscores and periods.
+//
+// These constraints are necessary since the plugin id is used as part of a filesystem path.
 func IsValidId(id string) bool {
 	if utf8.RuneCountInString(id) < MinIdLength {
 		return false
@@ -28,5 +35,5 @@ func IsValidId(id string) bool {
 		return false
 	}
 
-	return ValidId.MatchString(id)
+	return validId.MatchString(id)
 }