From f6d89e532aff4e8aa71fb6c9527a44dcc1850be8 Mon Sep 17 00:00:00 2001
From: Alexey Radul <axch@mit.edu>
Date: Fri, 27 May 2011 22:04:45 +0100
Subject: [PATCH] Warn that weak references are scary and hard to get right.
Redirect to provided higher-level abstractions.
---
doc/ref-manual/misc-datatypes.texi | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/doc/ref-manual/misc-datatypes.texi b/doc/ref-manual/misc-datatypes.texi
index 86828158a..c9e284782 100644
--- a/doc/ref-manual/misc-datatypes.texi
+++ b/doc/ref-manual/misc-datatypes.texi
@@ -892,6 +892,14 @@ a weak reference (but the cdr is still strong). The heavier-weight
count as holding the object in its key field strongly even if the
object in its datum field does.
+@strong{Warning}: Working with weak references is subtle and requires
+careful analysis; most programs should avoid working with them
+directly. The most common use cases for weak references ought to be
+served by hash tables (@pxref{Hash Tables}), which can employ various
+flavors of weak entry types, 1d tables (@pxref{1D Tables}), which hold
+their keys weakly, and the association table (@pxref{The Association
+Table}), which also holds its keys weakly.
+
@menu
* Weak Pairs::
* Ephemerons::
--
2.25.1