more plugin doc updates (#7767)

6 files changed, 47 insertions, 12 deletions

diff --git a/plugin/api.go b/plugin/api.go
index d7443d813..8d27bc794 100644
--- a/plugin/api.go
+++ b/plugin/api.go
@@ -7,8 +7,10 @@ import (
 	"github.com/mattermost/mattermost-server/model"
 )
 
-// API implementations 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.
+// 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.
 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.
diff --git a/plugin/example_hooks_test.go b/plugin/example_hello_user_test.go
index 7ca1cf5f0..4aefbc5f5 100644
--- a/plugin/example_hooks_test.go
+++ b/plugin/example_hello_user_test.go
@@ -8,16 +8,16 @@ import (
 	"github.com/mattermost/mattermost-server/plugin/rpcplugin"
 )
 
-type MyPlugin struct {
+type HelloUserPlugin struct {
 	api plugin.API
 }
 
-func (p *MyPlugin) OnActivate(api plugin.API) {
+func (p *HelloUserPlugin) OnActivate(api plugin.API) {
 	// Just save api for later when we need to look up users.
 	p.api = api
 }
 
-func (p *MyPlugin) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+func (p *HelloUserPlugin) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	if userId := r.Header.Get("Mattermost-User-Id"); userId == "" {
 		// Our visitor is unauthenticated.
 		fmt.Fprintf(w, "Hello, stranger!")
@@ -33,6 +33,6 @@ func (p *MyPlugin) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 
 // This example demonstrates a plugin that handles HTTP requests which respond by greeting the user
 // by name.
-func Example_plugin() {
-	rpcplugin.Main(&MyPlugin{})
+func Example_helloUser() {
+	rpcplugin.Main(&HelloUserPlugin{})
 }
diff --git a/plugin/example_hello_world_test.go b/plugin/example_hello_world_test.go
new file mode 100644
index 000000000..5dea28823
--- /dev/null
+++ b/plugin/example_hello_world_test.go
@@ -0,0 +1,20 @@
+package plugin_test
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/mattermost/mattermost-server/plugin/rpcplugin"
+)
+
+type HelloWorldPlugin struct{}
+
+func (p *HelloWorldPlugin) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	fmt.Fprintf(w, "Hello, world!")
+}
+
+// This example demonstrates a plugin that handles HTTP requests which respond by greeting the
+// world.
+func Example_helloWorld() {
+	rpcplugin.Main(&HelloWorldPlugin{})
+}
diff --git a/plugin/hooks.go b/plugin/hooks.go
index a40ac0e5c..04d5c7c14 100644
--- a/plugin/hooks.go
+++ b/plugin/hooks.go
@@ -7,10 +7,10 @@ import (
 	"net/http"
 )
 
-// Hooks represents an object that handles events for a plugin. 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.
+// 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.
 type Hooks interface {
 	// OnActivate is invoked when the plugin is activated. Implementations will usually want to save
 	// the api argument for later use. Loading configuration for the first time is also a commonly
diff --git a/plugin/plugin.go b/plugin/plugin.go
new file mode 100644
index 000000000..b14ab7ced
--- /dev/null
+++ b/plugin/plugin.go
@@ -0,0 +1,12 @@
+// Copyright (c) 2017-present Mattermost, Inc. All Rights Reserved.
+// See License.txt for license information.
+
+// The plugin package defines the primary interfaces for interacting with a Mattermost server: the
+// API and the hook interfaces.
+//
+// The API interface is used to perform actions. The Hook interface is used to respond to actions.
+//
+// Plugins should define a type that implements some of the methods from the Hook interface, then
+// pass an instance of that object into the rpcplugin package's Main function (See the HelloWorld
+// example.).
+package plugin
diff --git a/plugin/supervisor.go b/plugin/supervisor.go
index f3e576e99..76f20eaee 100644
--- a/plugin/supervisor.go
+++ b/plugin/supervisor.go
@@ -3,7 +3,8 @@
 
 package plugin
 
-// Supervisor provides the interface for an object that controls the execution of a plugin.
+// Supervisor provides the interface for an object that controls the execution of a plugin. This
+// type is only relevant to the server, and isn't used by the plugins themselves.
 type Supervisor interface {
 	Start() error
 	Stop() error