chore: add comments to examples

README.md

@@ -1,7 +1,7 @@
 # go-totp
 
 [![go1.22+](https://img.shields.io/badge/Go-1.22+-blue?logo=go)](https://github.com/KEINOS/go-totp/blob/main/.github/workflows/unit-tests.yml#L81 "Supported versions")
-[![Go Reference](https://pkg.go.dev/badge/github.com/KEINOS/go-totp.svg)](https://pkg.go.dev/github.com/KEINOS/go-totp/ "View document")
+[![Go Reference](https://pkg.go.dev/badge/github.com/KEINOS/go-totp.svg)](https://pkg.go.dev/github.com/KEINOS/go-totp/totp "View document")
 
 `go-totp` is a simple Go package to implement [Timebased-One-Time-Password](https://en.wikipedia.org/wiki/Time-based_one-time_password) authentication functionality, a.k.a. `TOTP`, to the Go app.
 

totp/example_test.go

@@ -16,6 +16,10 @@ import (
 //  Package Examples
 // ============================================================================
 
+// This example demonstrates how to generate a new secret key with default
+// options and validate the passcode.
+//
+// The generated key should be compatible with most TOTP authenticator apps.
 func Example() {
 	Issuer := "Example.com"            // name of the service
 	AccountName := "[email protected]" // name of the user
@@ -54,12 +58,19 @@ func Example() {
 	// * Validation result: Passcode is valid
 }
 
+// This example demonstrates how to generate a new secret key with custom options
+// and validate the passcode.
+//
+// Since most TOTP authenticator apps are based on SHA1 hashing algorithm to
+// generate the passcode, this example is useful when you need to generate the
+// passcode with a stronger hash algorithm such as SHA256 and SHA512.
 func Example_custom() {
 	// Generate a new secret key with custom options
 	Issuer := "Example.com"
 	AccountName := "[email protected]"
 
 	key, err := totp.GenerateKey(Issuer, AccountName,
+		// Algorithm choices are: MD5, SHA1, SHA256 and SHA512.
 		totp.WithAlgorithm(totp.Algorithm("SHA256")),
 		totp.WithPeriod(15),
 		totp.WithSecretSize(256),

totp/totp.go

@@ -4,6 +4,16 @@ authentication functionality, a.k.a. `TOTP`, to the Go app.
 
 Optionally, it supports ECDH key agreement protocol to share the same secret key
 between two parties.
+
+```shellsession
+# Install the module
+go get github.com/KEINOS/go-totp
+```
+
+```go
+// Use the package
+import "github.com/KEINOS/go-totp/totp"
+```
 */
 package totp