:weakness argument of make-hash-table is confusing (IMO)
every time i get to create a weak hash table i always get confused by the meaning of the :weakness argument.
after i spent a bit of time thinking, i've realized that it's because the values one must give to the :weakness argument means when the entries should be _preserved_.
i suggest to rename :weakness to :preserve-if with default value T meaning that the hash table is not weak.
if that change is considered too intrusive, then please consider an alternative docstring for make-hash-table:
By default, when :WEAKNESS is NIL, entries in a hashtable only get removed
when explicitly requested by REMHASH. (Note that the name :PRESERVE-IF
would more intuitively suggest the meaning of the values it accepts.)
When :WEAKNESS is not NIL, it specifies how the presence of a key or value
in the hash table preserves their hash table entries from garbage
- :KEY means that only those entries are guaranteed to be preserved whose
key is otherwise a live object (meaning that there's at least one
reference to it not considering the key slot of this hash table entry).
- :VALUE, symmetric to :KEY, means that only those entries are guaranteed
to be preserved whose value is otherwise a live object (meaning that
there's at least one reference to it not considering the value slot of
this hash table entry).
- :KEY-AND-VALUE means that both the key and the value must be live in
order to have a guarantee that the entry is preserved. Thus, the hash
table does not retain neither keys nor values from garbage collection;
if either one is eligible for collection then the entry also is.
- :KEY-OR-VALUE means that either the key or the value can preserve the
entry. Thus, hash table entries are eligible for collection when both
their key and value would otherwise be collected as garbage.