Document the global cache API

src/auxiliary/caches.jl

@@ -1,9 +1,35 @@
+"""
+    const GLOBAL_CACHES
+
+Registry of the global caches TensorKit maintains, as `name => cache` pairs.
+
+See also [`empty_globalcaches!`](@ref) and [`global_cache_info`](@ref).
+"""
 const GLOBAL_CACHES = Pair{Symbol, Any}[]
+
+"""
+    empty_globalcaches!()
+
+Empty every global cache in [`GLOBAL_CACHES`](@ref).
+These mostly contain bookkeeping for various different index manipulations and tensor structures,
+so clearing this out can free up some memory whenever you have a workflow that involves a large variety of structures.
+For example, you may want to clear the cache when working with different symmetries, or in algorithms that dynamically alter the sizes of tensors.
+Since everything is recomputed on demand, this is purely a memory measure.
+
+See also [`global_cache_info`](@ref) to display the status.
+"""
 function empty_globalcaches!()
     foreach(empty! ∘ last, GLOBAL_CACHES)
     return nothing
 end
 
+"""
+    global_cache_info([io::IO = stdout])
+
+Print the hit/miss statistics and current size of every global cache in [`GLOBAL_CACHES`](@ref).
+
+See also [`empty_globalcaches!`](@ref).
+"""
 function global_cache_info(io::IO = stdout)
     for (name, cache) in GLOBAL_CACHES
         println(io, name, ":\t", LRUCache.cache_info(cache))