From d79e6f2704ebda193ce4cdb5a05e0b949a58ed5d Mon Sep 17 00:00:00 2001
From: James Houlahan <james.houlahan@proton.ch>
Date: Sun, 2 Oct 2022 12:05:39 +0200
Subject: [PATCH] GODT-1815: Focus service docs

---
 internal/focus/client.go  |  2 ++
 internal/focus/service.go | 15 +++++++++++----
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/internal/focus/client.go b/internal/focus/client.go
index 982c427c..9014642d 100644
--- a/internal/focus/client.go
+++ b/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()
diff --git a/internal/focus/service.go b/internal/focus/service.go
index 18be2f10..0ce39cec 100644
--- a/internal/focus/service.go
+++ b/internal/focus/service.go
@@ -10,11 +10,13 @@ import (
 	"google.golang.org/protobuf/types/known/emptypb"
 )
 
-const (
-	Host = "127.0.0.1"
-	Port = 1042
-)
+// Host is the local host to listen on.
+const Host = "127.0.0.1"
 
+// 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()
 }