testing: clarify in docs that TestMain is advanced

Beginner and intermediate Go users periodically use TestMain when
requirements do not necessitate TestMain (exceeding least-mechanism
design). This commit expands package testing's documentation to convey
that the TestMain feature itself is somewhat low-level and potentially
unsuitable for casual testing where ordinary test functions would
suffice.

Fixes #42161
Updates #44200

Change-Id: I91ba0b048c3d6f79110fe8f0fbb58d896edca366
Reviewed-on: https://go-review.googlesource.com/c/go/+/334649
Trust: Ian Lance Taylor <iant@golang.org>
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>

diff --git a/src/testing/testing.go b/src/testing/testing.go
index eeee0aac1729a94114d56caab133bab02c949ad6..681f99ef93477c9dfd071cf5a65ffd05a2da1c46 100644 (file)
--- a/src/testing/testing.go
+++ b/src/testing/testing.go
@@ -233,6 +233,8 @@
 //             os.Exit(m.Run())
 //     }
 //
+// TestMain is a low-level primitive and should not be necessary for casual
+// testing needs, where ordinary test functions suffice.
 package testing
 
 import (