weak: massage package docs a little bit

This is an attempt to clarify the "advice" section of the package docs a
little bit and encourage a specific style of use for weak structures.
It's not perfect, but it's something.

Change-Id: Id84b76d207619cc2e78439c5c903ec9575199734
Reviewed-on: https://go-review.googlesource.com/c/go/+/633675
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Carlos Amedee <carlos@golang.org>
Auto-Submit: Michael Knyszek <mknyszek@google.com>

Author: mknyszek

src/weak/doc.go

@@ -6,21 +6,27 @@
 Package weak provides weak pointers with the goal of memory efficiency.
 The primary use-cases for weak pointers are for implementing caches,
 canonicalization maps (like the unique package), and for tying together
-the lifetimes of separate values.
+the lifetimes of separate values (for example, through a map with weak
+keys).
 
 ## Advice
 
 This package is intended to target niche use-cases like the unique
-package, not as a general replacement for regular Go pointers, maps,
-etc.
-Misuse of the structures in this package will generate unexpected and
+package, and the structures inside are not intended to be general
+replacements for regular Go pointers, maps, etc.
+Misuse of the structures in this package may generate unexpected and
 hard-to-reproduce bugs.
 Using the facilities in this package to try and resolve out-of-memory
-issues and/or memory leaks is very likely the wrong answer.
+issues requires careful consideration, and even so, will likely be the
+wrong answer if the solution does not fall into one of the listed
+use-cases above.
 
 The structures in this package are intended to be an implementation
 detail of the package they are used by (again, see the unique package).
-Avoid exposing weak structures across API boundaries, since that exposes
-users of your package to the subtleties of this package.
+If you're writing a package intended to be used by others, as a rule of
+thumb, avoid exposing the behavior of any weak structures in your package's
+API.
+Doing so will almost certainly make your package more difficult to use
+correctly.
 */
 package weak