docs for main plugin API

plugin/doc.go

@@ -18,13 +18,23 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 // THE SOFTWARE.
 
-// Package plugin defines the plugin API for writing thriftrw plugins.
+// Package plugin provides the API for writing ThriftRW plugins.
 //
-// Plugins take the form of an executable which runs the Main function.
+// Plugins are standalone programs with names in the format
+// thriftrw-plugin-$name where $name is the name of the plugin.
+//
+// 	// thriftrw-plugin-myfanceplugin/main.go
+// 	package main
+//
+// 	import "github.com/thriftrw/thriftrw-go/plugin"
 //
 // 	func main() {
-// 		plugin.Main(plugin.Plugin{
+// 		plugin.Main(&plugin.Plugin{
+// 			Name: "myfancyplugin",
 // 			// ...
 // 		})
 // 	}
+//
+// Note that the name in the executable MUST match the name in the Plugin
+// struct.
 package plugin

plugin/plugin.go

@@ -37,21 +37,24 @@ const _fastPathFrameSize = 10 * 1024 * 1024 // 10 MB
 
 var _proto = protocol.Binary
 
-// Plugin defines a plugin.
+// Plugin defines a ThriftRW plugin.
 type Plugin struct {
+	// Name of the plugin. The name of the executable providing this plugin MUST
+	// BE thriftrw-plugin-$name.
 	Name string
 
-	// Implement this to generate arbitrary code for services.
+	// If non-nil, this indicates that the plugin will generate code for Thrift
+	// services.
 	ServiceGenerator api.ServiceGenerator
 }
 
 // Main serves the given plugin. It is the entry point to the plugin system.
-// User-defined plugins should call Main with their Plugin definition.
+// User-defined plugins should call Main with their main function.
 func Main(p *Plugin) {
 	// The plugin communicates with the ThriftRW process over stdout and stdin
 	// of this process. Requests and responses are Thrift envelopes with a
 	// 4-byte big-endian encoded length prefix. Envelope names contain method
-	// names prefixed with the service name and a ":"
+	// names prefixed with the service name and a ":".
 
 	mainHandler := multiplex.NewHandler()