Update and format packages' documentation.

pkg/awsopt/awsopt.go

@@ -1,7 +1,12 @@
 /*
-Package awsopt provides functions to configure common AWS options for the official aws-sdk-go-v2 library.
-
-These common options can be easily used with other AWS-based packages in this library, such as s3 and sqs.
+Package awsopt provides functions to configure common AWS options for the
+official aws-sdk-go-v2 library.
+
+These common options can be easily used with other AWS-based packages in this
+library:
+  - awssecretcache
+  - s3
+  - sqs
 */
 package awsopt
 

pkg/awssecretcache/awssecretcache.go

@@ -1,12 +1,29 @@
 /*
-Package awssecretcache provides a simple client to retrieve and cache secrets from AWS Secrets Manager.
-To improve speed and reduce costs, the client uses a thread-safe local single-flight cache
-that avoids duplicate calls for the same secret.
-The cache has a maximum size and a time-to-live (TTL) for each entry.
-Duplicate calls for the same secret will wait for the first lookup to complete and return the same value.
+Package awssecretcache provides a simple client for retrieving and caching
+secrets from AWS Secrets Manager.
 
-This package is based on the official aws-sdk-go-v2 library.
+This package is based on the official aws-sdk-go-v2 library
+(https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/secretsmanager) and
+implements github.com/Vonage/gosrvlib/pkg/sfcache to provide a simple, local,
+thread-safe, fixed-size, and single-flight cache for AWS Secrets lookup calls.
 
-Reference: https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/secretsmanager.
+By caching previous values, awssecretcache improves the performance of secrets
+lookup by eliminating the need for repeated expensive requests.
+
+This package provides a local in-memory cache with a configurable maximum number
+of entries. The fixed size helps with efficient memory management and prevents
+excessive memory usage. The cache is thread-safe, allowing concurrent access
+without the need for external synchronization. It efficiently handles concurrent
+requests by sharing results from the first lookup, ensuring that only one
+request makes the expensive call, and avoiding unnecessary network load or
+resource starvation. Duplicate calls for the same key will wait for the first
+call to complete and return the same value.
+
+Each cache entry has a set time-to-live (TTL), so it will automatically expire.
+However, it is also possible to force the removal of a specific entry or reset
+the entire cache.
+
+This package is ideal for any Go application that heavily relies on AWS Secrets
+lookups.
 */
 package awssecretcache

pkg/bootstrap/bootstrap.go

@@ -1,6 +1,6 @@
 /*
-Package bootstrap provides a simple way to bootstrap an application with
-managed configuration, logging, metrics, application context, and shutdown signals.
+Package bootstrap provides a simple way to bootstrap an application with managed
+configuration, logging, metrics, application context, and shutdown signals.
 
 For an implementation example see in order:
   - examples/service/cmd/main.go

pkg/config/config.go

@@ -1,34 +1,50 @@
 /*
-Package config handles the configuration of a program.
-The configuration contains the set of initial parameter settings that are read at runtime by the program.
+Package config handles the configuration of a program. The configuration
+contains the set of initial parameter settings that are read at runtime by the
+program.
 
-This package allows plugging a fully-fledged configuration system into an application, taking care of the boilerplate code, common settings, configuration loading, and validation.
+This package allows plugging a fully-fledged configuration system into an
+application, taking care of the boilerplate code, common settings, configuration
+loading, and validation.
 
-Different configuration sources can be used during development, debugging, testing, or deployment.
-The configuration can be loaded from a local file, environment variables, or a remote configuration provider (e.g., Consul, etcd, etcd3, Firestore, NATS).
+Different configuration sources can be used during development, debugging,
+testing, or deployment. The configuration can be loaded from a local file,
+environment variables, or a remote configuration provider (e.g., Consul, etcd,
+etcd3, Firestore, NATS).
 
-This is a Viper-based implementation of the configuration model described in the following article:
-  - Nicola Asuni, 2014-09-13, "Software Configuration", https://technick.net/guides/software/software_configuration/
+This is a Viper-based implementation of the configuration model described in the
+following article:
+  - Nicola Asuni, 2014-09-13, "Software Configuration",
+    https://technick.net/guides/software/software_configuration/
 
 # Configuration Loading Strategy:
 
-To achieve maximum flexibility, the different configuration entry points are coordinated in the following sequence (1 has the lowest priority and 5 has the highest):
+To achieve maximum flexibility, the different configuration entry points are
+coordinated in the following sequence (1 has the lowest priority and 5 has the
+highest):
 
- 1. In the "myprog" program, the configuration parameters are defined as a data structure that can be easily mapped to and from a JSON object (or any other format supported by Viper like TOML, YAML, and HCL).
-    Each structure parameter is annotated with the "mapstructure" and "validate" tags to define the name mapping and the validation rules.
-    The parameters are initialized with constant default values.
+ 1. In the "myprog" program, the configuration parameters are defined as a data
+    structure that can be easily mapped to and from a JSON object (or any other
+    format supported by Viper like TOML, YAML, and HCL). Each structure
+    parameter is annotated with the "mapstructure" and "validate" tags to define
+    the name mapping and the validation rules. The parameters are initialized
+    with constant default values.
 
- 2. The program attempts to load the local "config.json" configuration file, and as soon as one is found, it overwrites the default values previously set.
+ 2. The program attempts to load the local "config.json" configuration file, and
+    as soon as one is found, it overwrites the default values previously set.
 
-    The configuration file is searched in the following ordered directories based on the Linux Filesystem Hierarchy Standard (FHS):
+    The configuration file is searched in the following ordered directories
+    based on the Linux Filesystem Hierarchy Standard (FHS):
 
     - ./
 
     - ~/.myprog/
 
     - /etc/myprog/
 
- 3. The program attempts to load the environmental variables that define the remote configuration system. If found, it overwrites the corresponding configuration parameters:
+ 3. The program attempts to load the environmental variables that define the
+    remote configuration system. If found, it overwrites the corresponding
+    configuration parameters:
 
     - [ENVIRONMENT VARIABLE NAME] → [CONFIGURATION PARAMETER NAME]
 
@@ -42,22 +58,30 @@ To achieve maximum flexibility, the different configuration entry points are coo
 
     - MYPROG_REMOTECONFIGDATA → remoteConfigData
 
- 4. If the "remoteConfigProvider" parameter is not empty, the program attempts to load the configuration data from the specified source.
-    This can be any remote source supported by the Viper library (e.g., Consul, etcd, etcd3, Firestore, NATS).
-    The configuration source can also be the "MYPROG_REMOTECONFIGDATA" environment variable as base64-encoded JSON when "MYPROG_REMOTECONFIGPROVIDER" is set to "envvar".
+ 4. If the "remoteConfigProvider" parameter is not empty, the program attempts
+    to load the configuration data from the specified source. This can be any
+    remote source supported by the Viper library (e.g., Consul, etcd, etcd3,
+    Firestore, NATS). The configuration source can also be the
+    "MYPROG_REMOTECONFIGDATA" environment variable as base64-encoded JSON when
+    "MYPROG_REMOTECONFIGPROVIDER" is set to "envvar".
 
- 5. Any specified command-line argument overwrites the corresponding configuration parameter.
+ 5. Any specified command-line argument overwrites the corresponding
+    configuration parameter.
 
  6. The configuration parameters are validated via the Validate() function.
 
 # Example:
 
-  - An implementation example of this configuration package can be found in examples/service/internal/cli/config.go
-    Note that the "log", "shutdown_timeout", and "remoteConfig" parameters are defined in this package as they are common to all programs.
+  - An implementation example of this configuration package can be found in
+    examples/service/internal/cli/config.go Note that the "log",
+    "shutdown_timeout", and "remoteConfig" parameters are defined in this
+    package as they are common to all programs.
 
-  - The configuration file format of the example service is defined by examples/service/resources/etc/gosrvlibexample/config.schema.json
+  - The configuration file format of the example service is defined by
+    examples/service/resources/etc/gosrvlibexample/config.schema.json
 
-  - The default configuration file of the example service is defined by examples/service/resources/etc/gosrvlibexample/config.json
+  - The default configuration file of the example service is defined by
+    examples/service/resources/etc/gosrvlibexample/config.json
 */
 package config
 

pkg/decint/decint.go

@@ -1,7 +1,9 @@
 /*
-Package decint provides utility functions to parse and represent decimal values as integers with a set precision.
+Package decint provides utility functions to parse and represent decimal values
+as integers with a set precision.
 
-The functions in this package are typically used to store and retrieve small currency values without loss of precision.
+The functions in this package are typically used to store and retrieve small
+currency values without loss of precision.
 
 Safe decimal values are limited up to 2^53 / 1e+6 = 9_007_199_254.740_992.
 */

pkg/dnscache/dnscache.go

@@ -1,7 +1,28 @@
 /*
-Package dnscache provides a thread-safe local single-flight DNS cache for LookupHost.
-The cache has a maximum size and a time-to-live (TTL) for each DNS entry.
-Duplicate LookupHost calls for the same host will wait for the first lookup to complete and return the same value.
+Package dnscache implements github.com/Vonage/gosrvlib/pkg/sfcache to provide a
+simple, local, thread-safe, fixed-size, and single-flight cache for DNS lookup
+calls.
+
+This package provides LookupHost() and DialContext() functions that can be used
+in place of the standard ones in the net package.
+
+By caching previous values, dnscache improves DNS lookup performance by
+eliminating the need for repeated expensive requests.
+
+This package provides a local in-memory cache with a configurable maximum number
+of entries. The fixed size helps with efficient memory management and prevents
+excessive memory usage. The cache is thread-safe, allowing concurrent access
+without the need for external synchronization. It efficiently handles concurrent
+requests by sharing results from the first lookup, ensuring only one request
+does the expensive call, and avoiding unnecessary network load or resource
+starvation. Duplicate calls for the same key will wait for the first call to
+complete and return the same value.
+
+Each cache entry has a set time-to-live (TTL), so it will automatically expire.
+However, it is also possible to force the removal of a specific DNS entry or
+reset the entire cache.
+
+This package is ideal for any Go application that relies heavily on DNS lookups.
 */
 package dnscache
 

pkg/encode/encode.go

@@ -1,6 +1,7 @@
 /*
-Package encode provides serialization and deserialization functions to safely transmit,
-store and retrieve data between different systems (e.g., databases, queues, caches, etc.).
+Package encode provides a collection of functions for safe serialization and
+deserialization of data between different systems, such as databases, queues,
+and caches.
 */
 package encode
 

pkg/encrypt/encrypt.go

@@ -1,5 +1,7 @@
 /*
-Package encrypt contains a collection of utility functions to encrypt and decrypt data.
+Package encrypt provides a collection of functions for safe encryption and
+decryption of data between different systems, such as databases, queues, and
+caches.
 */
 package encrypt
 

pkg/enumbitmap/enumbitmap.go

@@ -1,9 +1,11 @@
 /*
-Package enumbitmap provides functions to encode slices of enumeration strings into integer bitmap values and vice versa.
+Package enumbitmap provides functions to encode slices of enumeration strings
+into integer bitmap values and vice versa.
 
-Each bit correspond to a unique enumeration value.
+Each bit correspond to a unique enumeration value. It supports maximum 32 bit
+(33 distinct values including NONE).
 
-# Example:
+# Example with 8 bits:
 
 	00000000 =   0 dec = NONE
 	00000001 =   1 dec = FIRST

pkg/enumcache/enumcache.go

@@ -1,6 +1,8 @@
 /*
-Package enumcache provides simple thread-safe methods to store and retrieve enumeration sets with an integer ID and string name.
-It includes support for binary maps (enumbitmap), where each bit represents a different name in the enumeration set.
+Package enumcache provides a collection of thread-safe methods for storing and
+retrieving enumeration sets with integer IDs and string names. It includes
+support for binary maps (github.com/Vonage/gosrvlib/pkg/enumbitmap), where each
+bit represents a different name in the enumeration set.
 */
 package enumcache
 

pkg/enumdb/enumdb.go

@@ -1,9 +1,11 @@
 /*
-Package enumdb allows to load enumeration sets (enumcache) from multiple database tables.
+Package enumdb allows loading enumeration sets
+(github.com/Vonage/gosrvlib/pkg/enumcache) from multiple database tables.
 
-Each enumeration has a numerical ID ("id" on the database table as primary key) and a string name ("name" on the database table as unique string).
+Each enumeration has a numerical ID ("id" on the database table as the primary
+key) and a string name ("name" on the database table as a unique string).
 
-Example of MySQL database table that can be used with this package:
+Example of a MySQL database table that can be used with this package:
 
 	CREATE TABLE IF NOT EXISTS `example` (
 	  `id` SMALLINT UNSIGNED NOT NULL,

pkg/errtrace/trace.go

@@ -1,5 +1,7 @@
 /*
-Package errtrace provides a function to automatically trace errors.
+Package errtrace provides a function to automatically trace Go errors. Each
+error is annotated with the filename, line number, and function name where it
+was created.
 */
 package errtrace
 
@@ -8,7 +10,7 @@ import (
 	"runtime"
 )
 
-// Trace annotates the error message with the filename, line number and function name.
+// Trace annotates the error message with the filename, line number, and function name.
 func Trace(err error) error {
 	if err == nil {
 		return nil

pkg/exttools/exttools.go

@@ -1,9 +1,9 @@
 //go:build exttools
 
 /*
-Package exttools lists external build and test tools.
-These tools will appear in the `go.mod` file, but will not be a part of the build.
-They will be also excluded from the binaries as the "exttools" tag is not used.
+Package exttools lists external build and test tools. These tools will appear in
+the `go.mod` file but will not be included in the build process. They will also
+be excluded from the binaries since the "exttools" tag is not used.
 */
 package exttools
 

pkg/filter/filter.go

@@ -1,14 +1,18 @@
 /*
-Package filter provides generic rule-based filtering capabilities for struct slices.
+Package filter provides generic rule-based filtering capabilities for struct
+slices.
 
-Large sets of data can be filtered down to a subset of elements using a set of rules.
+Large sets of data can be filtered down to a subset of elements using a set of
+rules.
 
-The filter can be specified as a slice of slices of rules or as JSON (see filter_schema.json for the JSON schema).
-The first slice contains the rule sets that will be combined with a boolean AND.
-The sub-slices contain the rules that will be combined with a boolean OR.
+The filter can be specified as a slice of slices of rules or as JSON (see
+filter_schema.json for the JSON schema). The first slice contains the rule sets
+that will be combined with a boolean AND. The sub-slices contain the rules that
+will be combined with a boolean OR.
 
-A common application consists of users specifying a filter in a URL query parameter to reduce the amount of data to download on a GET request.
-The rules are parsed and applied server-side.
+A common application consists of users specifying a filter in a URL query
+parameter to reduce the amount of data to download on a GET request. The rules
+are parsed and applied server-side.
 
 # Example:
 
@@ -62,7 +66,8 @@ The supported rule types are listed in the rule.go file:
   - ">="     : Greater than or equal to - matches when the value is greater than or equal the reference.
 
 Every rule type can be prefixed with the symbol "!" to get the negated value.
-For example "!==" is equivalent to "Not Equal", matching values that are different.
+For example "!==" is equivalent to "Not Equal", matching values that are
+different.
 */
 package filter
 

pkg/healthcheck/healthcheck.go

@@ -1,9 +1,9 @@
 /*
 Package healthcheck provides a simple way to define health checks for external services or components.
 
-It provides an HTTP handler to collect the results of the health checks concurrently.
+It provides an HTTP handler to collect and return the results of the health checks concurrently.
 
-For an implementation example see the examples/service/internal/cli/bind.go file.
+For an implementation example, see the file examples/service/internal/cli/bind.go.
 */
 package healthcheck
 

pkg/httpclient/httpclient.go

@@ -1,5 +1,7 @@
 /*
-Package httpclient provides a configurable and instrumented HTTP client with common options.
-It includes a trace ID header support and common logging capabilities, including the ability to dump the redacted request and response messages.
+Package httpclient provides a configurable and instrumented HTTP client with
+common options. It includes support for trace ID headers and common logging
+capabilities, such as the ability to dump redacted request and response
+messages.
 */
 package httpclient

pkg/httpretrier/httpretrier.go

@@ -1,18 +1,21 @@
 /*
-Package httpretrier provides the ability to automatically repeat HTTP requests based on user-defined conditions.
+Package httpretrier provides the ability to automatically repeat HTTP requests
+based on user-defined conditions.
 
-Any part of the returned http.Response (e.g., StatusCode) and error can be used to define the retry function (retry condition).
-The default behavior is to retry only in case of an error.
+Any part of the returned http.Response (e.g., StatusCode) and error can be used
+to define the retry function (retry condition). The default behavior is to retry
+only in case of an error.
 
-This package also offers ready-made retry functions that can be used for most cases:
+This package also offers ready-made retry functions that can be used for most
+cases:
 
-- RetryIfForWriteRequests
-- RetryIfForReadRequests
+  - RetryIfForWriteRequests
+  - RetryIfForReadRequests
 
-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.
+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 httpretrier