more package docs

Author: nicolaasuni-vonage

pkg/randkey/randkey.go

@@ -1,5 +1,5 @@
 /*
-Package randkey provides utility functions to generate random uint64 keys.
+Package randkey provides utility functions to generate random uint64 keys in different formats.
 */
 package randkey
 

pkg/redact/redact.go

@@ -1,4 +1,8 @@
-// Package redact contains utilities functions to obscure sensitive data.
+/*
+Package redact contains utility functions to obscure sensitive data.
+
+This is useful for logging and debugging, where sensitive data should not be exposed.
+*/
 package redact
 
 import (

pkg/retrier/retrier.go

@@ -1,4 +1,15 @@
-// Package retrier allow to retry execute a function in case of errors.
+/*
+Package retrier provides the ability to automatically repeat a user-defined function based on the error status.
+
+The default behavior is to retry in case of any error.
+
+This package also offers ready-made DefaultRetryIf function that can be used for most cases.
+
+Additionally, it allows you to set the maximum number of retries,
+the delay after the first failed attempt,
+the time multiplication factor to determine the successive delay value,
+and the jitter used to introduce randomness and avoid request collisions.
+*/
 package retrier
 
 import (
@@ -46,6 +57,7 @@ type Retrier struct {
 	taskError         error
 }
 
+// defaultRetrier returns a new instance of Retrier with default configuration values.
 func defaultRetrier() *Retrier {
 	return &Retrier{
 		attempts:    DefaultAttempts,
@@ -100,6 +112,8 @@ func (r *Retrier) Run(ctx context.Context, task TaskFn) error {
 	}
 }
 
+// setTimer sets the timer for the Retrier with the given duration.
+// If the timer is already running, it is stopped and the timer channel is drained before resetting.
 func (r *Retrier) setTimer(d time.Duration) {
 	if !r.timer.Stop() {
 		// make sure to drain timer channel before reset
@@ -112,6 +126,9 @@ func (r *Retrier) setTimer(d time.Duration) {
 	r.timer.Reset(d)
 }
 
+// exec executes the given task function with a timeout and handles retries if necessary.
+// It returns true if the task should not be retried or if the maximum number of attempts has been reached.
+// Otherwise, it returns false to indicate that the task should be retried.
 func (r *Retrier) exec(ctx context.Context, task TaskFn) bool {
 	tctx, cancel := context.WithTimeout(ctx, r.timeout)
 	r.taskError = task(tctx)

pkg/s3/s3.go

@@ -1,2 +1,6 @@
-// Package s3 provides a client for AWS S3 bucket.
+/*
+Package s3 provides a simple client to interact with a AWS S3 bucket, including the ability to upload, download, and delete objects.
+
+It is based on the official aws-sdk-go-v2 library.
+*/
 package s3

pkg/slack/client.go

@@ -1,4 +1,3 @@
-// Package slack is a basic Slack API client to send messages via a Webhook.
 package slack
 
 import (
@@ -44,7 +43,8 @@ type Client struct {
 }
 
 // New creates a new instance of the Slack service client.
-// The arguments other than "addr" are optional. They can be set in the Webhook configuration or in each individual message.
+// The arguments other than "addr" (Slack Webhook URL) are optional,
+// they can be set in the Webhook configuration or in each individual message.
 func New(addr, username, iconEmoji, iconURL, channel string, opts ...Option) (*Client, error) {
 	address, err := url.Parse(addr)
 	if err != nil {

pkg/slack/slack.go

@@ -0,0 +1,6 @@
+/*
+Package slack is a basic client for the official Slack API to send messages via a Webhook.
+
+Ref.: https://api.slack.com/messaging/webhooks
+*/
+package slack

pkg/sleuth/sleuth.go

@@ -1,5 +1,8 @@
-// Package sleuth contains the implementation of a basic Sleuth.io API client.
-// Ref.: https://help.sleuth.io/sleuth-api
+/*
+Package sleuth is a basic client for the official Sleuth.io API to register deployments, manual changes, custom incident impact, and custom metric impact.
+
+Ref.: https://help.sleuth.io/sleuth-api
+*/
 package sleuth
 
 import (