Add some plugin docs (#7757)

* add some plugin docs

* one more comment

* spacing

* example simplification

3 files changed, 47 insertions, 1 deletions

diff --git a/plugin/api.go b/plugin/api.go
index e9a2892fc..d7443d813 100644
--- a/plugin/api.go
+++ b/plugin/api.go
@@ -7,6 +7,8 @@ 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.
 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_hooks_test.go
new file mode 100644
index 000000000..7ca1cf5f0
--- /dev/null
+++ b/plugin/example_hooks_test.go
@@ -0,0 +1,38 @@
+package plugin_test
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/mattermost/mattermost-server/plugin"
+	"github.com/mattermost/mattermost-server/plugin/rpcplugin"
+)
+
+type MyPlugin struct {
+	api plugin.API
+}
+
+func (p *MyPlugin) 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) {
+	if userId := r.Header.Get("Mattermost-User-Id"); userId == "" {
+		// Our visitor is unauthenticated.
+		fmt.Fprintf(w, "Hello, stranger!")
+	} else if user, err := p.api.GetUser(userId); err == nil {
+		// Greet the user by name!
+		fmt.Fprintf(w, "Welcome back, %v!", user.Username)
+	} else {
+		// This won't happen in normal circumstances, but let's just be safe.
+		w.WriteHeader(http.StatusInternalServerError)
+		fmt.Fprintf(w, err.Error())
+	}
+}
+
+// This example demonstrates a plugin that handles HTTP requests which respond by greeting the user
+// by name.
+func Example_plugin() {
+	rpcplugin.Main(&MyPlugin{})
+}
diff --git a/plugin/hooks.go b/plugin/hooks.go
index c5daec45b..a40ac0e5c 100644
--- a/plugin/hooks.go
+++ b/plugin/hooks.go
@@ -7,8 +7,14 @@ 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.
 type Hooks interface {
-	// OnActivate is invoked when the plugin is activated.
+	// 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
+	// done here.
 	OnActivate(API) error
 
 	// OnDeactivate is invoked when the plugin is deactivated. This is the plugin's last chance to