Add more documentation for method and types (#79)

* Updated package Godoc

* Updated go code to specify that `WithName()` method is optional

* Added formatting in README.md

* Updated godoc for `WithName()` method

* Updated godoc for `NewWithSignals()` constructor

* Updated app example to use rootCtx

* Updated godoc for `Register()` constructor

* Updated godoc for `Hook` type

README.md

@@ -80,7 +80,7 @@ if err := terminator.Wait(appCtx, 20*time.Second); err != nil {
 
 # 👀 Versioning
 
-The library follows SemVer policy. With the release of v1.0.0 the public API is stable. 
+The library follows SemVer policy. With the release of **v1.0.0** the _public API is stable_. 
 
 # 📚 Example
 

doc.go

@@ -6,23 +6,27 @@
 
 	It is possible to set individual timeouts for each registered termination hook and global termination timeout for the whole application.
 
+	Optionally a Hook may have a name (using Hook.WithName). It might be handy only if the Logger injected into Terminator instance to
+	log internal termination lifecycle events.
+
 	Examples
 
 	Example code for generic application components:
 
 		func main() {
-			// Define Orders:
+			// Define termination Orders:
 			const (
 				HTTPServerTerminationOrder graterm.Order = 1
 				DBTerminationOrder         graterm.Order = 2
 			)
 
 			// create new Terminator instance:
 			terminator, appCtx := graterm.NewWithSignals(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+			terminator.SetLogger(log.Default()) // Optional step
 
 			// Register HTTP Server termination hook:
 			terminator.WithOrder(HTTPServerTerminationOrder).
-				WithName("HTTP Server").
+				WithName("HTTP Server"). // setting a Name is optional and will be useful only if logger instance provided
 				Register(1*time.Second, func(ctx context.Context) {
 					log.Println("terminating HTTP Server...")
 					defer log.Println("...HTTP Server terminated")
@@ -57,11 +61,13 @@
 
 			// create new Terminator instance:
 			terminator, appCtx := graterm.NewWithSignals(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+			terminator.SetLogger(log.Default()) // Optional step
 
 			// Create an HTTP Server and add one simple handler into it:
 			httpServer := &http.Server{
-				Addr:    ":8080",
-				Handler: http.DefaultServeMux,
+				ReadHeaderTimeout: 60 * time.Second, // fix for potential Slowloris Attack
+				Addr:              ":8080",
+				Handler:           http.DefaultServeMux,
 			}
 			http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
 				fmt.Fprintf(w, "hello, world!")
@@ -76,7 +82,7 @@
 
 			// Register HTTP Server termination hook:
 			terminator.WithOrder(HTTPServerTerminationOrder).
-				WithName("HTTPServer").
+				WithName("HTTPServer"). // setting a Name is optional and will be useful only if logger instance provided
 				Register(10*time.Second, func(ctx context.Context) {
 					if err := httpServer.Shutdown(ctx); err != nil {
 						log.Printf("shutdown HTTP Server: %+v\n", err)

example_test.go

@@ -58,10 +58,11 @@ func ExampleTerminator_WithOrder_1() {
 
 	// create new Terminator instance:
 	terminator, appCtx := graterm.NewWithSignals(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	terminator.SetLogger(log.Default()) // Optional step
 
 	// Register HTTP Server termination hook:
 	terminator.WithOrder(HTTPServerTerminationOrder).
-		WithName("HTTP Server").
+		WithName("HTTP Server"). // setting a Name is optional and will be useful only if logger instance provided
 		Register(1*time.Second, func(ctx context.Context) {
 			log.Println("terminating HTTP Server...")
 			defer log.Println("...HTTP Server terminated")
@@ -76,7 +77,7 @@ func ExampleTerminator_WithOrder_1() {
 
 	// Register Database termination hook:
 	terminator.WithOrder(DBTerminationOrder).
-		WithName("DB").
+		WithName("DB"). // setting a Name is optional and will be useful only if logger instance provided
 		Register(1*time.Second, func(ctx context.Context) {
 			log.Println("terminating DB...")
 			defer log.Println("...DB terminated")
@@ -102,6 +103,7 @@ func ExampleTerminator_WithOrder_2() {
 
 	// create new Terminator instance:
 	terminator, appCtx := graterm.NewWithSignals(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	terminator.SetLogger(log.Default()) // Optional step
 
 	// Create an HTTP Server and add one simple handler into it:
 	httpServer := &http.Server{
@@ -121,7 +123,7 @@ func ExampleTerminator_WithOrder_2() {
 
 	// Register HTTP Server termination hook:
 	terminator.WithOrder(HTTPServerTerminationOrder).
-		WithName("HTTPServer").
+		WithName("HTTPServer"). // setting a Name is optional and will be useful only if logger instance provided
 		Register(10*time.Second, func(ctx context.Context) {
 			if err := httpServer.Shutdown(ctx); err != nil {
 				log.Printf("shutdown HTTP Server: %+v\n", err)
@@ -164,6 +166,7 @@ func ExampleHook_WithName() {
 
 	// create new Terminator instance:
 	terminator, appCtx := graterm.NewWithSignals(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	terminator.SetLogger(log.Default()) // Optional step
 
 	// Register some hooks:
 	terminator.WithOrder(HTTPServerTerminationOrder).

hook.go

@@ -18,9 +18,10 @@ const (
 // Lower order - higher priority.
 type Order int
 
-// Hook is a registered termination hook.
+// Hook is a registered ordered termination unit of work.
+// I.e., the code that needs to be executed to perform resource cleanup or any other maintenance while shutting down the application.
 //
-// Do not create a Hook instance manually, use Terminator.WithOrder() method instead to get a Hook instance.
+// Do NOT create a Hook instance manually, use Terminator.WithOrder() method instead to get a Hook instance.
 type Hook struct {
 	terminator *Terminator // terminator is a pointer to Terminator instance that holds registered Hooks.
 
@@ -31,6 +32,9 @@ type Hook struct {
 }
 
 // WithName sets (optional) human-readable name of the registered termination [Hook].
+//
+// The Hook name will be useful only if Logger instance has been injected (using Terminator.SetLogger method) into Terminator
+// to log internal termination lifecycle events.
 func (h *Hook) WithName(name string) *Hook {
 	h.name = name
 	return h
@@ -39,6 +43,9 @@ func (h *Hook) WithName(name string) *Hook {
 // Register registers termination [Hook] that should finish execution in less than given timeout.
 //
 // Timeout duration must be greater than zero; if not, timeout of 1 min will be used.
+//
+// The context value passed into hookFunc will be used only for cancellation signaling.
+// I.e. to signal that Terminator will no longer wait on Hook to finish termination.
 func (h *Hook) Register(timeout time.Duration, hookFunc func(ctx context.Context)) {
 	if timeout <= 0 {
 		timeout = defaultTimeout

internal/example/example.go

@@ -44,8 +44,12 @@ func main() {
 
 	logger.Println("Application started...")
 
-	terminator, appCtx := graterm.NewWithSignals(context.Background(), syscall.SIGINT, syscall.SIGTERM)
-	terminator.SetLogger(logger)
+	// ...Some root context for the whole application... (or it can be just context.Background())
+	rootCtx, rootCancel := context.WithCancel(context.Background())
+	defer rootCancel()
+
+	terminator, appCtx := graterm.NewWithSignals(rootCtx, syscall.SIGINT, syscall.SIGTERM)
+	terminator.SetLogger(logger) // Optional step
 
 	// Wire application components:
 	slowDB := NewSlowDB(terminator, logger)
@@ -116,7 +120,7 @@ func (s *Server) Init() {
 	}()
 
 	s.terminator.WithOrder(HTTPServerTerminationOrder).
-		WithName("HTTPServer").
+		WithName("HTTPServer"). // setting a Name is optional and will be useful only if logger instance provided
 		Register(httpServerTerminationTimeout, func(ctx context.Context) {
 			s.logger.Println("terminating HTTP Server component...")
 			defer s.logger.Println("...HTTP Server component terminated")
@@ -141,7 +145,7 @@ func NewMessaging(terminator *graterm.Terminator, logger *log.Logger) *Messaging
 func (m *Messaging) Init() {
 	defer m.logger.Println("Messaging initialized")
 	m.terminator.WithOrder(MessagingTerminationOrder).
-		WithName("Messaging").
+		WithName("Messaging"). // setting a Name is optional and will be useful only if logger instance provided
 		Register(messagingTerminationTimeout, func(ctx context.Context) {
 			m.logger.Println("terminating Messaging component...")
 			defer m.logger.Println("...Messaging component terminated")
@@ -160,7 +164,7 @@ func NewFastDB(terminator *graterm.Terminator, logger *log.Logger) *FastDB {
 func (d *FastDB) Init() {
 	defer d.logger.Println("FastDB initialized")
 	d.terminator.WithOrder(FastDBTerminationOrder).
-		WithName("FastDB").
+		WithName("FastDB"). // setting a Name is optional and will be useful only if logger instance provided
 		Register(fastDBTerminationTimeout, func(ctx context.Context) {
 			d.logger.Println("terminating FastDB component...")
 			defer d.logger.Println("...FastDB component terminated")
@@ -181,7 +185,7 @@ func NewSlowDB(terminator *graterm.Terminator, logger *log.Logger) *SlowDB {
 func (d *SlowDB) Init() {
 	defer d.logger.Println("SlowDB initialized")
 	d.terminator.WithOrder(SlowDBTerminationOrder).
-		WithName("SlowDB").
+		WithName("SlowDB"). // setting a Name is optional and will be useful only if logger instance provided
 		Register(slowDBTerminationTimeout, func(ctx context.Context) {
 			d.logger.Println("terminating SlowDB component...")
 			defer d.logger.Println("...SlowDB component terminated")

terminator.go

@@ -25,6 +25,9 @@ type Terminator struct {
 
 // NewWithSignals creates a new instance of component Terminator.
 //
+// If the given appCtx parameter is canceled, the termination process will start for already registered Hook instances
+// after calling Terminator.Wait method.
+//
 // Example of useful signals might be: [syscall.SIGINT], [syscall.SIGTERM].
 //
 // Note: this method will start internal monitoring goroutine.