Add info.Doc to plugin help documentation (#6)

bufbuild · Sep 28, 2024 · b68f3e6 · b68f3e6
1 parent 70a4bf4
commit b68f3e6
Show file tree

Hide file tree

Showing 5 changed files with 35 additions and 8 deletions.
diff --git a/check/internal/example/cmd/buf-plugin-timestamp-suffix/main.go b/check/internal/example/cmd/buf-plugin-timestamp-suffix/main.go
@@ -82,6 +82,7 @@ var (
 			URL:           "https://github.com/bufbuild/bufplugin-go",
 			SPDXLicenseID: "apache-2.0",
 			LicenseURL:    "https://github.com/bufbuild/bufplugin-go/blob/main/LICENSE",
+			DocShort:      `A simple plugin that checks that all google.protobuf.Timestamp fields end in a specific suffix (default is "_time").`,
 		},
 	}
 )

diff --git a/check/server.go b/check/server.go
@@ -77,7 +77,21 @@ func NewServer(spec *Spec, options ...ServerOption) (pluginrpc.Server, error) {
 		infov1pluginrpc.RegisterPluginInfoServiceServer(serverRegistrar, pluginInfoServiceServer)
 	}
 
-	return pluginrpc.NewServer(pluginrpcSpec, serverRegistrar)
+	// Add documentation to -h/--help.
+	var pluginrpcServerOptions []pluginrpc.ServerOption
+	if spec.Info != nil {
+		pluginInfo, err := info.NewPluginInfoForSpec(spec.Info)
+		if err != nil {
+			return nil, err
+		}
+		if doc := pluginInfo.Doc(); doc != nil {
+			pluginrpcServerOptions = append(
+				pluginrpcServerOptions,
+				pluginrpc.ServerWithDoc(doc.String()),
+			)
+		}
+	}
+	return pluginrpc.NewServer(pluginrpcSpec, serverRegistrar, pluginrpcServerOptions...)
 }
 
 // ServerOption is an option for Server.

diff --git a/info/doc.go b/info/doc.go
@@ -93,7 +93,8 @@ func (d *doc) toProto() *infov1.Doc {
 
 func (*doc) isDoc() {}
 
-func docForProtoDoc(protoDoc *infov1.Doc) (Doc, error) {
+// Need to keep as pointer for Go nil is not nil problem.
+func docForProtoDoc(protoDoc *infov1.Doc) (*doc, error) {
 	if protoDoc == nil {
 		return nil, nil
 	}

diff --git a/info/license.go b/info/license.go
@@ -118,7 +118,8 @@ func (l *license) toProto() *infov1.License {
 
 func (*license) isLicense() {}
 
-func licenseForProtoLicense(protoLicense *infov1.License) (License, error) {
+// Need to keep as pointer for Go nil is not nil problem.
+func licenseForProtoLicense(protoLicense *infov1.License) (*license, error) {
 	if protoLicense == nil {
 		return nil, nil
 	}

diff --git a/info/plugin_info.go b/info/plugin_info.go
@@ -92,15 +92,17 @@ func NewPluginInfoForSpec(spec *Spec) (PluginInfo, error) {
 // *** PRIVATE ***
 
 type pluginInfo struct {
-	url     *url.URL
-	license License
-	doc     Doc
+	url *url.URL
+	// Need to keep as pointer for Go nil is not nil problem.
+	license *license
+	// Need to keep as pointer for Go nil is not nil problem.
+	doc *doc
 }
 
 func newPluginInfo(
 	url *url.URL,
-	license License,
-	doc Doc,
+	license *license,
+	doc *doc,
 ) (*pluginInfo, error) {
 	if url != nil && url.Host == "" {
 		return nil, fmt.Errorf("url %v must be absolute", url)
@@ -117,10 +119,18 @@ func (p *pluginInfo) URL() *url.URL {
 }
 
 func (p *pluginInfo) License() License {
+	// Go nil is not nil problem.
+	if p.license == nil {
+		return nil
+	}
 	return p.license
 }
 
 func (p *pluginInfo) Doc() Doc {
+	// Go nil is not nil problem.
+	if p.doc == nil {
+		return nil
+	}
 	return p.doc
 }