GODT-1815: Focus service docs

internal/focus/client.go

@@ -11,6 +11,8 @@ import (
 	"google.golang.org/protobuf/types/known/emptypb"
 )
 
+// TryRaise tries to raise the application by dialing the focus service.
+// It returns true if the service is running and the application was told to raise.
 func TryRaise() bool {
 	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
 	defer cancel()

internal/focus/service.go

@@ -10,11 +10,13 @@ import (
 	"google.golang.org/protobuf/types/known/emptypb"
 )
 
-const (
+// Host is the local host to listen on.
-	Host = "127.0.0.1"
+const Host = "127.0.0.1"
-	Port = 1042
-)
 
+// Port is the port to listen on.
+var Port = 1042
+
+// FocusService is a gRPC service that can be used to raise the application.
 type FocusService struct {
 	proto.UnimplementedFocusServer
 
@@ -23,6 +25,8 @@ type FocusService struct {
 	raiseCh  chan struct{}
 }
 
+// NewService creates a new focus service.
+// It listens on the local host and port 1042 (by default).
 func NewService() (*FocusService, error) {
 	listener, err := net.Listen("tcp", net.JoinHostPort(Host, fmt.Sprint(Port)))
 	if err != nil {
@@ -46,15 +50,18 @@ func NewService() (*FocusService, error) {
 	return service, nil
 }
 
+// Raise implements the gRPC FocusService interface; it raises the application.
 func (service *FocusService) Raise(context.Context, *emptypb.Empty) (*emptypb.Empty, error) {
 	service.raiseCh <- struct{}{}
 	return &emptypb.Empty{}, nil
 }
 
+// GetRaiseCh returns a channel on which events are sent when the application should be raised.
 func (service *FocusService) GetRaiseCh() <-chan struct{} {
 	return service.raiseCh
 }
 
+// Close closes the service.
 func (service *FocusService) Close() {
 	service.server.Stop()
 }