gorumsimpl: correct exported call API contracts

.vscode/gorums.txt

@@ -262,6 +262,7 @@ syncrq
 synctest
 TAILPID
 tcpstats
+testdata
 testprotos
 testrace
 testutils
@@ -285,6 +286,7 @@ underflowing
 unexport
 Unexported
 unicast
+unicasts
 unmarshal
 unmarshaled
 unmarshaling

cmd/protoc-gen-gorums/gengorums/template_client.go

@@ -106,11 +106,12 @@ func genClients(g *protogen.GeneratedFile, services []*protogen.Service) {
 var configClient = `
 {{$errEmptyConfig := use "gorums.ErrEmptyConfig" .GenFile}}
 {{$service := .Service.GoName}}
-// {{.Names.Interface}} is the client API for the quorum calls and multicasts of
-// the {{$service}} service. Its calls execute on the configuration given to
-// [{{.Names.Constructor}}]. If that configuration is empty, every call returns
-// [{{$errEmptyConfig}}].
-type {{.Names.Interface}} interface {
+{{$serviceComments := .Service.Comments.Leading}}
+// {{.Names.Interface}} is the client API for {{$service}} quorum calls and
+// multicasts on the client's configuration. If the configuration is empty, no
+// message is sent and the call fails with [{{$errEmptyConfig}}].
+{{if ne $serviceComments ""}}//
+{{$serviceComments}}{{end}}type {{.Names.Interface}} interface {
 {{.Methods}}
 }
 
@@ -130,11 +131,12 @@ type {{.Names.Impl}} struct {
 var nodeClient = `
 {{$errNoNode := use "gorums.ErrNoNode" .GenFile}}
 {{$service := .Service.GoName}}
-// {{.Names.Interface}} is the client API for the remote calls and unicasts
-// of the {{$service}} service. Its calls execute on the node given to
-// [{{.Names.Constructor}}]. If that node is nil, every call returns
-// [{{$errNoNode}}].
-type {{.Names.Interface}} interface {
+{{$serviceComments := .Service.Comments.Leading}}
+// {{.Names.Interface}} is the client API for {{$service}} remote calls and
+// unicasts on the client's node. If the node is nil, no message is sent and the
+// call fails with [{{$errNoNode}}].
+{{if ne $serviceComments ""}}//
+{{$serviceComments}}{{end}}type {{.Names.Interface}} interface {
 {{.Methods}}
 }
 

cmd/protoc-gen-gorums/gengorums/template_server.go

@@ -53,8 +53,10 @@ var serverInterface = `
 {{$genFile := .GenFile}}
 {{range .Services -}}
 {{$service := .Service.GoName}}
-// {{.Names.Interface}} is the server-side API for the {{$service}} Service
-type {{.Names.Interface}} interface {
+{{$serviceComments := .Service.Comments.Leading}}
+// {{.Names.Interface}} is the server API for {{$service}}.
+{{if ne $serviceComments ""}}//
+{{$serviceComments}}{{end}}type {{.Names.Interface}} interface {
 	{{- range .Service.Methods}}
 	{{- if isOneway .}}
 	{{.GoName}}({{$context}}, *{{in $genFile .}})

internal/testprotos/testdata/calltypes/importmsgs/importmsgs_gorums.pb.go.golden

@@ -20,10 +20,9 @@ const (
 	_ = gorumsimpl.EnforceVersion(gorumsimpl.MaxVersion - 12)
 )
 
-// QuorumCallClient is the client API for the quorum calls and multicasts of
-// the QuorumCall service. Its calls execute on the configuration given to
-// [NewQuorumCallClient]. If that configuration is empty, every call returns
-// [gorums.ErrEmptyConfig].
+// QuorumCallClient is the client API for QuorumCall quorum calls and
+// multicasts on the client's configuration. If the configuration is empty, no
+// message is sent and the call fails with [gorums.ErrEmptyConfig].
 type QuorumCallClient interface {
 	// QuorumCall executes a quorum call on the client's configuration. Use
 	// terminal methods like Majority(), First(), or Threshold(n) to retrieve the
@@ -49,7 +48,7 @@ func (c quorumCallClient) QuorumCall(ctx context.Context, in *msgs.Request) *gor
 	return gorumsimpl.QuorumCall[*msgs.Request, *msgs.Response](ctx, c.config, in, "internal.testprotos.calltypes.importmsgs.QuorumCall.QuorumCall")
 }
 
-// QuorumCallServer is the server-side API for the QuorumCall Service
+// QuorumCallServer is the server API for QuorumCall.
 type QuorumCallServer interface {
 	QuorumCall(gorums.ServerContext, *msgs.Request) (*msgs.Response, error)
 }

internal/testprotos/testdata/calltypes/multicast/multicast_gorums.pb.go.golden

@@ -23,10 +23,9 @@ const (
 // Reference imports to suppress errors if they are not otherwise used.
 var _ emptypb.Empty
 
-// MulticastClient is the client API for the quorum calls and multicasts of
-// the Multicast service. Its calls execute on the configuration given to
-// [NewMulticastClient]. If that configuration is empty, every call returns
-// [gorums.ErrEmptyConfig].
+// MulticastClient is the client API for Multicast quorum calls and
+// multicasts on the client's configuration. If the configuration is empty, no
+// message is sent and the call fails with [gorums.ErrEmptyConfig].
 type MulticastClient interface {
 	// Multicast starts a one-way call on the client's configuration; no reply
 	// is returned. Use gorums.MapRequest to send a different message to each node.
@@ -59,7 +58,7 @@ func (c multicastClient) Multicast(ctx context.Context, in *Request) *gorums.One
 	return gorumsimpl.Multicast(ctx, c.config, in, "internal.testprotos.calltypes.multicast.Multicast.Multicast")
 }
 
-// MulticastServer is the server-side API for the Multicast Service
+// MulticastServer is the server API for Multicast.
 type MulticastServer interface {
 	Multicast(gorums.ServerContext, *Request)
 }

internal/testprotos/testdata/calltypes/multiservice/multiservice_gorums.pb.go.golden

@@ -23,10 +23,9 @@ const (
 // Reference imports to suppress errors if they are not otherwise used.
 var _ emptypb.Empty
 
-// AlphaClient is the client API for the quorum calls and multicasts of
-// the Alpha service. Its calls execute on the configuration given to
-// [NewAlphaClient]. If that configuration is empty, every call returns
-// [gorums.ErrEmptyConfig].
+// AlphaClient is the client API for Alpha quorum calls and
+// multicasts on the client's configuration. If the configuration is empty, no
+// message is sent and the call fails with [gorums.ErrEmptyConfig].
 type AlphaClient interface {
 	// Heartbeat executes a quorum call on the client's configuration. Use
 	// terminal methods like Majority(), First(), or Threshold(n) to retrieve the
@@ -48,10 +47,9 @@ type alphaClient struct {
 	config Config
 }
 
-// AlphaNodeClient is the client API for the remote calls and unicasts
-// of the Alpha service. Its calls execute on the node given to
-// [NewAlphaNodeClient]. If that node is nil, every call returns
-// [gorums.ErrNoNode].
+// AlphaNodeClient is the client API for Alpha remote calls and
+// unicasts on the client's node. If the node is nil, no message is sent and the
+// call fails with [gorums.ErrNoNode].
 type AlphaNodeClient interface {
 	// Read executes a remote call on the client's node and returns its
 	// reply.
@@ -73,10 +71,9 @@ type alphaNodeClient struct {
 	node *Node
 }
 
-// BetaClient is the client API for the quorum calls and multicasts of
-// the Beta service. Its calls execute on the configuration given to
-// [NewBetaClient]. If that configuration is empty, every call returns
-// [gorums.ErrEmptyConfig].
+// BetaClient is the client API for Beta quorum calls and
+// multicasts on the client's configuration. If the configuration is empty, no
+// message is sent and the call fails with [gorums.ErrEmptyConfig].
 type BetaClient interface {
 	// Heartbeat executes a quorum call on the client's configuration. Use
 	// terminal methods like Majority(), First(), or Threshold(n) to retrieve the
@@ -130,13 +127,13 @@ func (c betaClient) Write(ctx context.Context, in *Request) *gorums.OnewayCall[*
 	return gorumsimpl.Multicast(ctx, c.config, in, "internal.testprotos.calltypes.multiservice.Beta.Write")
 }
 
-// AlphaServer is the server-side API for the Alpha Service
+// AlphaServer is the server API for Alpha.
 type AlphaServer interface {
 	Heartbeat(gorums.ServerContext, *Request) (*Response, error)
 	Read(gorums.ServerContext, *Request) (*Response, error)
 }
 
-// BetaServer is the server-side API for the Beta Service
+// BetaServer is the server API for Beta.
 type BetaServer interface {
 	Heartbeat(gorums.ServerContext, *Request) (*Response, error)
 	Write(gorums.ServerContext, *Request)

internal/testprotos/testdata/calltypes/quorumcall/quorumcall_gorums.pb.go.golden

@@ -19,10 +19,9 @@ const (
 	_ = gorumsimpl.EnforceVersion(gorumsimpl.MaxVersion - 12)
 )
 
-// QuorumCallClient is the client API for the quorum calls and multicasts of
-// the QuorumCall service. Its calls execute on the configuration given to
-// [NewQuorumCallClient]. If that configuration is empty, every call returns
-// [gorums.ErrEmptyConfig].
+// QuorumCallClient is the client API for QuorumCall quorum calls and
+// multicasts on the client's configuration. If the configuration is empty, no
+// message is sent and the call fails with [gorums.ErrEmptyConfig].
 type QuorumCallClient interface {
 	// QuorumCall executes a quorum call on the client's configuration. Use
 	// terminal methods like Majority(), First(), or Threshold(n) to retrieve the
@@ -48,7 +47,7 @@ func (c quorumCallClient) QuorumCall(ctx context.Context, in *Request) *gorums.C
 	return gorumsimpl.QuorumCall[*Request, *Response](ctx, c.config, in, "internal.testprotos.calltypes.quorumcall.QuorumCall.QuorumCall")
 }
 
-// QuorumCallServer is the server-side API for the QuorumCall Service
+// QuorumCallServer is the server API for QuorumCall.
 type QuorumCallServer interface {
 	QuorumCall(gorums.ServerContext, *Request) (*Response, error)
 }

internal/testprotos/testdata/clientnames/clientnames_gorums.pb.go.golden

@@ -23,10 +23,9 @@ const (
 // Reference imports to suppress errors if they are not otherwise used.
 var _ emptypb.Empty
 
-// ClientNamesClient is the client API for the quorum calls and multicasts of
-// the ClientNames service. Its calls execute on the configuration given to
-// [NewClientNamesClient]. If that configuration is empty, every call returns
-// [gorums.ErrEmptyConfig].
+// ClientNamesClient is the client API for ClientNames quorum calls and
+// multicasts on the client's configuration. If the configuration is empty, no
+// message is sent and the call fails with [gorums.ErrEmptyConfig].
 type ClientNamesClient interface {
 	// Config is a quorum call.
 	Config(ctx context.Context, in *Request) *gorums.Call[*Request, *Response]
@@ -54,10 +53,9 @@ type clientNamesClient struct {
 	config Config
 }
 
-// ClientNamesNodeClient is the client API for the remote calls and unicasts
-// of the ClientNames service. Its calls execute on the node given to
-// [NewClientNamesNodeClient]. If that node is nil, every call returns
-// [gorums.ErrNoNode].
+// ClientNamesNodeClient is the client API for ClientNames remote calls and
+// unicasts on the client's node. If the node is nil, no message is sent and the
+// call fails with [gorums.ErrNoNode].
 type ClientNamesNodeClient interface {
 	// Node is a remote call.
 	Node(ctx context.Context, in *Request) (*Response, error)
@@ -102,7 +100,7 @@ func (c clientNamesNodeClient) ForNode(ctx context.Context, in *Request) *gorums
 	return gorumsimpl.Unicast(ctx, c.node, in, "internal.testprotos.clientnames.ClientNames.ForNode")
 }
 
-// ClientNamesServer is the server-side API for the ClientNames Service
+// ClientNamesServer is the server API for ClientNames.
 type ClientNamesServer interface {
 	Config(gorums.ServerContext, *Request) (*Response, error)
 	WithConfig(gorums.ServerContext, *Request)