Merge pull request #8 from buildkite/update-doc-comments

Update doc comments for Marshal{JSON,YAML}

plugin.go

@@ -25,18 +25,20 @@ type Plugin struct {
 	Config any
 }
 
-// MarshalJSON returns the plugin in "one-key object" form, or "single string"
-// form (no config, only plugin source). Plugin sources are marshalled into "full"
-// form.
+// MarshalJSON returns the plugin in "one-key object" form. Plugin sources are
+// marshalled into "full" form. Plugins originally specified as a single string
+// (no config, only source) are canonicalised into "one-key object" with config
+// null.
 func (p *Plugin) MarshalJSON() ([]byte, error) {
 	// NB: MarshalYAML (as seen below) never returns an error.
 	o, _ := p.MarshalYAML()
 	return json.Marshal(o)
 }
 
-// MarshalYAML returns the plugin in either "one-item map" form, or "scalar"
-// form (no config, only plugin source). Plugin sources are marshalled into "full"
-// form.
+// MarshalYAML returns the plugin in either "one-item map" form. Plugin sources
+// are marshalled into "full" form.  Plugins originally specified as a single
+// string (no config, only source) are canonicalised into "one-item map" with
+// config nil.
 func (p *Plugin) MarshalYAML() (any, error) {
 	return map[string]any{
 		p.FullSource(): p.Config,