[gcc r14-4085] doc: GTY((cache)) documentation tweak

[Jason Merrill <jason@gcc.gnu.org>]

https://gcc.gnu.org/g:93996cfb308ffc633a23d0f1b72bcdc086bed864

commit r14-4085-g93996cfb308ffc633a23d0f1b72bcdc086bed864
Author: Jason Merrill <jason@redhat.com>
Date:   Fri Sep 8 11:27:26 2023 -0400

    doc: GTY((cache)) documentation tweak
    
    gcc/ChangeLog:
    
            * doc/gty.texi: Add discussion of cache vs. deletable.

Diff:
---
 gcc/doc/gty.texi | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/gcc/doc/gty.texi b/gcc/doc/gty.texi
index 15f9fa07405..1dfe4652644 100644
--- a/gcc/doc/gty.texi
+++ b/gcc/doc/gty.texi
@@ -306,6 +306,13 @@ called on that variable between the mark and sweep phases of garbage
 collection.  The gt_clear_cache function is free to mark blocks as used, or to
 clear pointers in the variable.
 
+In a hash table, the @samp{gt_cleare_cache} function discards entries
+if the key is not marked, or marks the value if the key is marked.
+
+Note that caches should generally use @code{deletable} instead;
+@code{cache} is only preferable if the value is impractical to
+recompute from the key when needed.
+
 @findex deletable
 @item deletable