From 2105c099d84b3dd9d7de70699d8c9febcc527dbe Mon Sep 17 00:00:00 2001
From: "Gustavo L de Mello (Guz)" <contact@guz.one>
Date: Fri, 24 Jan 2025 16:40:52 -0300
Subject: [PATCH] docs(blogo,metadata): Metadata implementation docs

---
 blogo/metadata/metadata.go | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/blogo/metadata/metadata.go b/blogo/metadata/metadata.go
index bceabc2..266e222 100644
--- a/blogo/metadata/metadata.go
+++ b/blogo/metadata/metadata.go
@@ -181,13 +181,50 @@ func GetMetadata(m any) (Metadata, error) {
 	return data, nil
 }
 
+// Types may implement this interface to add [Metadata] to their objects that can
+// be easily accessed via [Get], [Set], [Delete] and [GetMetadata]
 type WithMetadata interface {
+	// Returns the underlying [Metadata] of the type.
+	//
+	// If the [Metadata] is empty and/or the type doesn't have any data associated with
+	// it, implementations should return a empty [Metadata] (such as Map(map[string]any{}))
+	// and should never return a nil interface.
 	Metadata() Metadata
 }
 
+// Minimal interface for the Metadata data. This data is used to easily pass information
+// between [plugin.Plugin]'s files and file systems.
+//
+// Implementations of this interface can store their metadata in any way possible,
+// may it be with a simple underlying map[string]any or a network accessed storage.
+//
+// Plugins may add prefixed to their keys to minimize conflicts between other plugins'
+// data. The convention for key strings is "<prefix>.<key-name>", all lowercase and
+// kabeb-cased.
+//
+// Other objects and interfaces, such as [fs.FS] and [fs.File] may implement this
+// interface directly or use the [WithMetadata] interface.
+//
+// [TypedMetadata] may also be implemented to optimize calls via [GetTyped].
 type Metadata interface {
+	// Gets the value of the specified key.
+	//
+	// Implementations should return [ErrNotFound] if the provided key doesn't have
+	// any associated value with it.
 	Get(key string) (any, error)
+	// Sets the value of the specified key.
+	//
+	// If the key cannot be created or have it's underlying value changed,
+	// implementations should return [ErrImmutable].
+	//
+	// If the type of v is different from the stored value, implementations may return
+	// [ErrInvalidType] if they can't accept different types.
 	Set(key string, v any) error
+	// Deletes the key from metadata. Implementations that cannot delete the key directly,
+	// should set the value a appropriated zero or implementations' default value for that key.
+	//
+	// If the key cannot be created or have it's underlying value changed,
+	// implementations should return [ErrImmutable].
 	Delete(key string) error
 }