From c80e0f9e939a9ade411b3926e84f97fa607fd09c Mon Sep 17 00:00:00 2001
From: Teddy Wing
Date: Thu, 18 May 2023 15:34:25 +0200
Subject: Add package documentation

---
 capturedrefrace.go | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/capturedrefrace.go b/capturedrefrace.go
index b58ed9d..e7d0c45 100644
--- a/capturedrefrace.go
+++ b/capturedrefrace.go
@@ -16,7 +16,38 @@
 // along with Gocapturedrefrace. If not, see
 // <https://www.gnu.org/licenses/>.
 
-// TODO: package documentation.
+// Package capturedrefrace defines an Analyzer that checks for captured
+// references in goroutine closures.
+//
+// # Analyzer capturedrefrace
+//
+// capturedrefrace: report captured variable references in goroutine
+// closures.
+//
+// Goroutines that run function closures can capture reference variables from
+// outer scopes which could lead to data races. This analyzer checks closures
+// run by goroutines and reports uses of all variables declared in outer
+// scopes, as well as arguments to the closure with a pointer type.
+//
+// For example:
+//
+//	func (r *Record) CapturedReference() {
+//		capturedReference := 0
+//		spline := &Spline{Curvature: 5.0}
+//
+//		go func(s *Spline) {
+//			capturedReference += 1 // closure captures the variable
+//				// 'capturedReference' in a goroutine, which could
+//				// lead to data races
+//
+//			if capturedReference > 0 {
+//				r.reticulateSplines() // goroutine closure captures 'r'
+//			}
+//
+//			s.Curvature = 3.0 // 's' is a pointer type which could
+//				// lead to data races
+//		}(spline)
+//	}
 package capturedrefrace
 
 import (
-- 
cgit v1.2.3