Extend package documentation

Signed-off-by: Leandro López (inkel) <[email protected]>

disk.go

@@ -2,25 +2,25 @@ package unused
 
 import "time"
 
-// Disk reprensents an unused disk on a given cloud provider
+// Disk represents an unused disk on a given cloud provider.
 type Disk interface {
-	// ID should return a unique ID for a disk within each cloud provider
+	// ID should return a unique ID for a disk within each cloud
+	// provider.
 	ID() string
 
-	// Provider returns a string indicating the provider this disk belongs to
+	// Provider returns a string indicating the provider this disk
+	// belongs to.
 	Provider() Provider
 
-	// Name returns the disk name
+	// Name returns the disk name.
 	Name() string
 
-	// CreatedAt returns the time.Time when the disk was created
+	// CreatedAt returns the time when the disk was created.
 	CreatedAt() time.Time
 
-	// LastUsedAt returns the date when the disk was last mounted, or
-	// time.Zero if this information isn't available (i.e. limited in
-	// AWS and non-existing in Azure)
+	// LastUsedAt returns the date when the disk was last used.
 	LastUsedAt() time.Time
 
-	// Meta returns the disk metadata
+	// Meta returns the disk metadata.
 	Meta() Meta
 }

disks.go

@@ -2,23 +2,28 @@ package unused
 
 import "sort"
 
-// Disks is a collection of Disk
+// Disks is a collection of Disk.
 type Disks []Disk
 
+// ByFunc is the type of sorting functions for Disks.
 type ByFunc func(p, q Disk) bool
 
+// ByProvider sorts a Disks collection by provider name.
 func ByProvider(p, q Disk) bool {
 	return p.Provider().Name() < q.Provider().Name()
 }
 
+// ByName sorts a Disks collection by disk name.
 func ByName(p, q Disk) bool {
 	return p.Name() < q.Name()
 }
 
+// ByCreatedAt sorts a Disks collection by disk creation time.
 func ByCreatedAt(p, q Disk) bool {
 	return p.CreatedAt().Before(q.CreatedAt())
 }
 
+// Sort sorts the collection by the given function.
 func (d Disks) Sort(by ByFunc) {
 	sort.Slice(d, func(i, j int) bool { return by(d[i], d[j]) })
 }

doc.go

@@ -0,0 +1,11 @@
+// Package unsued provides the basic interfaces to obtain information
+// and in some cases, manipulate, unused resources in different Cloud
+// Service Providers (CSPs).
+//
+// Currently only unused disks are supported.
+//
+// The following providers are already implemented:
+//   - Google Cloud Platform (GCP)
+//   - Amazon Web Services (AWS)
+//   - Azure
+package unused

meta.go

@@ -5,8 +5,10 @@ import (
 	"strings"
 )
 
+// Meta is a map of key/value pairs.
 type Meta map[string]string
 
+// Keys returns all the keys in the map sorted alphabetically.
 func (m Meta) Keys() []string {
 	ks := make([]string, 0, len(m))
 	for k := range m {
@@ -16,6 +18,7 @@ func (m Meta) Keys() []string {
 	return ks
 }
 
+// String returns a string representation of metadata.
 func (m Meta) String() string {
 	var s strings.Builder
 	for i, k := range m.Keys() {
@@ -29,6 +32,8 @@ func (m Meta) String() string {
 	return s.String()
 }
 
+// Matches returns true when the given key exists in the map with the
+// given value.
 func (m Meta) Matches(key, val string) bool {
 	return m[key] == val
 }

provider.go

@@ -2,17 +2,18 @@ package unused
 
 import "context"
 
-// Provider represents a cloud provider
+// Provider represents a cloud provider.
 type Provider interface {
-	// Name returns the provider name
+	// Name returns the provider name.
 	Name() string
 
-	// ListUnusedDisks returns a list of unused disks for the given provider
+	// ListUnusedDisks returns a list of unused disks for the given
+	// provider.
 	ListUnusedDisks(ctx context.Context) (Disks, error)
 
-	// Meta returns the provider metadata
+	// Meta returns the provider metadata.
 	Meta() Meta
 
-	// Delete deletes a disk from the provider
+	// Delete deletes a disk from the provider.
 	Delete(ctx context.Context, disk Disk) error
 }