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, 71 insertions, 0 deletions

diff --git a/plugin/example_help_test.go b/plugin/example_help_test.go
new file mode 100644
index 000000000..3f9be9a20
--- /dev/null
+++ b/plugin/example_help_test.go
@@ -0,0 +1,71 @@
+package plugin_test
+
+import (
+	"strings"
+
+	"github.com/mattermost/mattermost-server/model"
+	"github.com/mattermost/mattermost-server/plugin"
+)
+
+type HelpPlugin struct {
+	plugin.MattermostPlugin
+
+	TeamName    string
+	ChannelName string
+
+	channelId string
+}
+
+func (p *HelpPlugin) OnConfigurationChange() error {
+	// Reuse the default implementation of OnConfigurationChange to automatically load the
+	// required TeamName and ChannelName.
+	if err := p.MattermostPlugin.OnConfigurationChange(); err != nil {
+		p.API.LogError(err.Error())
+		return nil
+	}
+
+	team, err := p.API.GetTeamByName(p.TeamName)
+	if err != nil {
+		p.API.LogError("failed to find team", "team_name", p.TeamName)
+		return nil
+	}
+
+	channel, err := p.API.GetChannelByName(p.ChannelName, team.Id)
+	if err != nil {
+		p.API.LogError("failed to find channel", "channel_name", p.ChannelName)
+		return nil
+	}
+
+	p.channelId = channel.Id
+
+	return nil
+}
+
+func (p *HelpPlugin) MessageHasBeenPosted(c *plugin.Context, post *model.Post) {
+	// Ignore posts not in the configured channel
+	if post.ChannelId != p.channelId {
+		return
+	}
+
+	// Ignore posts this plugin made.
+	if sentByPlugin, _ := post.Props["sent_by_plugin"].(bool); sentByPlugin {
+		return
+	}
+
+	// Ignore posts without a plea for help.
+	if !strings.Contains(post.Message, "help") {
+		return
+	}
+
+	p.API.SendEphemeralPost(post.UserId, &model.Post{
+		ChannelId: p.channelId,
+		Message:   "You asked for help? Checkout https://about.mattermost.com/help/",
+		Props: map[string]interface{}{
+			"sent_by_plugin": true,
+		},
+	})
+}
+
+func Example_helpPlugin() {
+	plugin.ClientMain(&HelpPlugin{})
+}