From 039260fcf6a3b37629c10862987041c726e1036d Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Sat, 4 Apr 2026 09:48:02 +0000
Subject: [PATCH] test(ax): enforce exported field usage examples

Co-Authored-By: Virgil <virgil@lethean.io>
---
 compact.go          |  3 +++
 conventions_test.go | 40 ++++++++++++++++++++++++++++++++++++++++
 scope.go            |  6 ++++--
 3 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/compact.go b/compact.go
index 2fed74c..23b198f 100644
--- a/compact.go
+++ b/compact.go
@@ -13,8 +13,11 @@ var defaultArchiveOutputDirectory = ".core/archive/"
 
 // Usage example: `options := store.CompactOptions{Before: time.Now().Add(-90 * 24 * time.Hour), Output: "/tmp/archive", Format: "gzip"}`
 type CompactOptions struct {
+	// Usage example: `options := store.CompactOptions{Before: time.Now().Add(-90 * 24 * time.Hour)}`
 	Before time.Time
+	// Usage example: `options := store.CompactOptions{Output: "/tmp/archive"}`
 	Output string
+	// Usage example: `options := store.CompactOptions{Format: "zstd"}`
 	Format string
 }
 
diff --git a/conventions_test.go b/conventions_test.go
index 48e56d2..fb5bccf 100644
--- a/conventions_test.go
+++ b/conventions_test.go
@@ -124,6 +124,46 @@ func TestConventions_Exports_Good_UsageExamples(t *testing.T) {
 	assert.Empty(t, missing, "exported declarations must include a usage example in their doc comment")
 }
 
+func TestConventions_Exports_Good_FieldUsageExamples(t *testing.T) {
+	files := repoGoFiles(t, func(name string) bool {
+		return core.HasSuffix(name, ".go") && !core.HasSuffix(name, "_test.go")
+	})
+
+	var missing []string
+	for _, path := range files {
+		file := parseGoFile(t, path)
+		for _, decl := range file.Decls {
+			node, ok := decl.(*ast.GenDecl)
+			if !ok {
+				continue
+			}
+			for _, spec := range node.Specs {
+				typeSpec, ok := spec.(*ast.TypeSpec)
+				if !ok || !typeSpec.Name.IsExported() {
+					continue
+				}
+				structType, ok := typeSpec.Type.(*ast.StructType)
+				if !ok {
+					continue
+				}
+				for _, field := range structType.Fields.List {
+					for _, fieldName := range field.Names {
+						if !fieldName.IsExported() {
+							continue
+						}
+						if !core.Contains(commentText(field.Doc), "Usage example:") {
+							missing = append(missing, core.Concat(path, ": ", typeSpec.Name.Name, ".", fieldName.Name))
+						}
+					}
+				}
+			}
+		}
+	}
+
+	slices.Sort(missing)
+	assert.Empty(t, missing, "exported struct fields must include a usage example in their doc comment")
+}
+
 func TestConventions_Exports_Good_NoCompatibilityAliases(t *testing.T) {
 	files := repoGoFiles(t, func(name string) bool {
 		return core.HasSuffix(name, ".go") && !core.HasSuffix(name, "_test.go")
diff --git a/scope.go b/scope.go
index 8a2bee2..b029fe6 100644
--- a/scope.go
+++ b/scope.go
@@ -26,8 +26,10 @@ type QuotaConfig struct {
 type ScopedStore struct {
 	backingStore *Store
 	namespace    string
-	MaxKeys      int
-	MaxGroups    int
+	// Usage example: `scopedStore.MaxKeys = 100`
+	MaxKeys int
+	// Usage example: `scopedStore.MaxGroups = 10`
+	MaxGroups int
 
 	scopedWatchersLock sync.Mutex
 	scopedWatchers     map[uintptr]*scopedWatcherBinding
-- 
2.45.3