From d49714cf6c2d68f771865cc4b3a264d5c3282485 Mon Sep 17 00:00:00 2001
From: KEINOS <github@keinos.com>
Date: Sat, 24 Aug 2024 21:09:22 +0900
Subject: [PATCH] chore: add comments to examples

---
 README.md            |  2 +-
 totp/example_test.go | 11 +++++++++++
 totp/totp.go         | 10 ++++++++++
 3 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 23596bc..3360095 100644
--- a/README.md
+++ b/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.
 
diff --git a/totp/example_test.go b/totp/example_test.go
index d5dabd5..04c3b3b 100644
--- a/totp/example_test.go
+++ b/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 := "alice@example.com" // 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 := "alice@example.com"
 
 	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),
diff --git a/totp/totp.go b/totp/totp.go
index 7748774..9adbc79 100644
--- a/totp/totp.go
+++ b/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