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, 16 insertions, 13 deletions

diff --git a/plugin/interface_generator/main.go b/plugin/interface_generator/main.go
index 8cbaf4249..4b8b6786f 100644
--- a/plugin/interface_generator/main.go
+++ b/plugin/interface_generator/main.go
@@ -210,20 +210,20 @@ package plugin
 {{range .HooksMethods}}
 
 func init() {
-	HookNameToId["{{.Name}}"] = {{.Name}}Id
+	hookNameToId["{{.Name}}"] = {{.Name}}Id
 }
 
-type {{.Name}}Args struct {
+type {{.Name | obscure}}Args struct {
 	{{structStyle .Params}}
 }
 
-type {{.Name}}Returns struct {
+type {{.Name | obscure}}Returns struct {
 	{{structStyle .Return}}
 }
 
-func (g *HooksRPCClient) {{.Name}}{{funcStyle .Params}} {{funcStyle .Return}} {
-	_args := &{{.Name}}Args{ {{valuesOnly .Params}} }
-	_returns := &{{.Name}}Returns{}
+func (g *hooksRPCClient) {{.Name}}{{funcStyle .Params}} {{funcStyle .Return}} {
+	_args := &{{.Name | obscure}}Args{ {{valuesOnly .Params}} }
+	_returns := &{{.Name | obscure}}Returns{}
 	if g.implemented[{{.Name}}Id] {
 		if err := g.client.Call("Plugin.{{.Name}}", _args, _returns); err != nil {
 			g.log.Error("RPC call {{.Name}} to plugin failed.", mlog.Err(err))
@@ -232,7 +232,7 @@ func (g *HooksRPCClient) {{.Name}}{{funcStyle .Params}} {{funcStyle .Return}} {
 	return {{destruct "_returns." .Return}}
 }
 
-func (s *HooksRPCServer) {{.Name}}(args *{{.Name}}Args, returns *{{.Name}}Returns) error {
+func (s *hooksRPCServer) {{.Name}}(args *{{.Name | obscure}}Args, returns *{{.Name | obscure}}Returns) error {
 	if hook, ok := s.impl.(interface {
 		{{.Name}}{{funcStyle .Params}} {{funcStyle .Return}}
 	}); ok {
@@ -246,24 +246,24 @@ func (s *HooksRPCServer) {{.Name}}(args *{{.Name}}Args, returns *{{.Name}}Return
 
 {{range .APIMethods}}
 
-type {{.Name}}Args struct {
+type {{.Name | obscure}}Args struct {
 	{{structStyle .Params}}
 }
 
-type {{.Name}}Returns struct {
+type {{.Name | obscure}}Returns struct {
 	{{structStyle .Return}}
 }
 
-func (g *APIRPCClient) {{.Name}}{{funcStyle .Params}} {{funcStyle .Return}} {
-	_args := &{{.Name}}Args{ {{valuesOnly .Params}} }
-	_returns := &{{.Name}}Returns{}
+func (g *apiRPCClient) {{.Name}}{{funcStyle .Params}} {{funcStyle .Return}} {
+	_args := &{{.Name | obscure}}Args{ {{valuesOnly .Params}} }
+	_returns := &{{.Name | obscure}}Returns{}
 	if err := g.client.Call("Plugin.{{.Name}}", _args, _returns); err != nil {
 		g.log.Error("RPC call to {{.Name}} API failed.", mlog.Err(err))
 	}
 	return {{destruct "_returns." .Return}}
 }
 
-func (s *APIRPCServer) {{.Name}}(args *{{.Name}}Args, returns *{{.Name}}Returns) error {
+func (s *apiRPCServer) {{.Name}}(args *{{.Name | obscure}}Args, returns *{{.Name | obscure}}Returns) error {
 	if hook, ok := s.impl.(interface {
 		{{.Name}}{{funcStyle .Params}} {{funcStyle .Return}}
 	}); ok {
@@ -295,6 +295,9 @@ func generateGlue(info *PluginInterfaceInfo) {
 		"destruct": func(structPrefix string, fields *ast.FieldList) string {
 			return FieldListDestruct(structPrefix, fields, info.FileSet)
 		},
+		"obscure": func(name string) string {
+			return "Z_" + name
+		},
 	}
 
 	hooksTemplate, err := template.New("hooks").Funcs(templateFunctions).Parse(hooksTemplate)