Basic manifest docs (#7806)

* basic manifest docs

* add a bit more documentation

* space out fields for better godoc formatting

model/manifest.go

@@ -22,40 +22,110 @@ const (
 )
 
 type PluginOption struct {
+	// The display name for the option.
 	DisplayName string `json:"display_name" yaml:"display_name"`
-	Value       string `json:"value" yaml:"value"`
+
+	// The string value for the option.
+	Value string `json:"value" yaml:"value"`
 }
 
 type PluginSetting struct {
-	DisplayName        string          `json:"display_name" yaml:"display_name"`
+	// The display name for the setting.
-	Type               string          `json:"type" yaml:"type"`
+	DisplayName string `json:"display_name" yaml:"display_name"`
-	HelpText           string          `json:"help_text" yaml:"help_text"`
+
-	RegenerateHelpText string          `json:"regenerate_help_text,omitempty" yaml:"regenerate_help_text,omitempty"`
+	// The type of the setting.
-	Default            interface{}     `json:"default" yaml:"default"`
+	//
-	Options            []*PluginOption `json:"options,omitempty" yaml:"options,omitempty"`
+	// "bool" will result in a boolean true or false setting.
+	//
+	// "dropdown" will result in a string setting that allows the user to select from a list of
+	// pre-defined options.
+	//
+	// "generated" will result in a string setting that is set to a random, cryptographically secure
+	// string.
+	//
+	// "radio" will result in a string setting that allows the user to select from a short selection
+	// of pre-defined options.
+	//
+	// "text" will result in a string setting that can be typed in manually.
+	Type string `json:"type" yaml:"type"`
+
+	// The help text to display to the user.
+	HelpText string `json:"help_text" yaml:"help_text"`
+
+	// The help text to display alongside the "Regenerate" button for settings of the "generated" type.
+	RegenerateHelpText string `json:"regenerate_help_text,omitempty" yaml:"regenerate_help_text,omitempty"`
+
+	// The default value of the setting.
+	Default interface{} `json:"default" yaml:"default"`
+
+	// For "radio" or "dropdown" settings, this is the list of pre-defined options that the user can choose
+	// from.
+	Options []*PluginOption `json:"options,omitempty" yaml:"options,omitempty"`
 }
 
 type PluginSettingsSchema struct {
-	Header   string                    `json:"header" yaml:"header"`
+	// Optional text to display above the settings.
-	Footer   string                    `json:"footer" yaml:"footer"`
+	Header string `json:"header" yaml:"header"`
+
+	// Optional text to display below the settings.
+	Footer string `json:"footer" yaml:"footer"`
+
+	// A mapping of setting keys to schema definitions.
 	Settings map[string]*PluginSetting `json:"settings" yaml:"settings"`
 }
 
+// The plugin manifest defines the metadata required to load and present your plugin. The manifest
+// file should be named plugin.json or plugin.yaml and placed in the top of your
+// plugin bundle.
+//
+// Example plugin.yaml:
+//
+//     id: com.mycompany.myplugin
+//     name: My Plugin
+//     description: This is my plugin. It does stuff.
+//     backend:
+//         executable: myplugin
+//     settings_schema:
+//         settings:
+//             enable_extra_thing:
+//                 type: bool
+//                 display_name: Enable Extra Thing
+//                 help_text: When true, an extra thing will be enabled!
+//                 default: false
 type Manifest struct {
-	Id             string                `json:"id" yaml:"id"`
+	// The id is a globally unique identifier that represents your plugin. Reverse-DNS notation
-	Name           string                `json:"name,omitempty" yaml:"name,omitempty"`
+	// using a name you control is a good option. For example, "com.mycompany.myplugin".
-	Description    string                `json:"description,omitempty" yaml:"description,omitempty"`
+	Id string `json:"id" yaml:"id"`
-	Version        string                `json:"version" yaml:"version"`
+
-	Backend        *ManifestBackend      `json:"backend,omitempty" yaml:"backend,omitempty"`
+	// The name to be displayed for the plugin.
-	Webapp         *ManifestWebapp       `json:"webapp,omitempty" yaml:"webapp,omitempty"`
+	Name string `json:"name,omitempty" yaml:"name,omitempty"`
+
+	// A description of what your plugin is and does.
+	Description string `json:"description,omitempty" yaml:"description,omitempty"`
+
+	// A version number for your plugin. Semantic versioning is recommended: http://semver.org
+	Version string `json:"version" yaml:"version"`
+
+	// If your plugin extends the server, you'll need define backend.
+	Backend *ManifestBackend `json:"backend,omitempty" yaml:"backend,omitempty"`
+
+	// If your plugin extends the web app, you'll need to define webapp.
+	Webapp *ManifestWebapp `json:"webapp,omitempty" yaml:"webapp,omitempty"`
+
+	// To allow administrators to configure your plugin via the Mattermost system console, you can
+	// provide your settings schema.
 	SettingsSchema *PluginSettingsSchema `json:"settings_schema,omitempty" yaml:"settings_schema,omitempty"`
 }
 
 type ManifestBackend struct {
+	// The path to your executable binary. This should be relative to the root of your bundle and the
+	// location of the manifest file.
 	Executable string `json:"executable" yaml:"executable"`
 }
 
 type ManifestWebapp struct {
+	// The path to your webapp bundle. This should be relative to the root of your bundle and the
+	// location of the manifest file.
 	BundlePath string `json:"bundle_path" yaml:"bundle_path"`
 }