Update cooked_index comment

This updates the cooked_index comment with some notes about object
lifetimes, in an attempt to make navigating this code a bit simpler.

Approved-By: Simon Marchi <simon.marchi@efficios.com>

diff --git a/gdb/dwarf2/cooked-index.h b/gdb/dwarf2/cooked-index.h
index 1848798bfad2dece70882e0d0163cacabc7ad53f..c16afa04037246867a76364687ffa0c5d78aaba5 100644 (file)
--- a/gdb/dwarf2/cooked-index.h
+++ b/gdb/dwarf2/cooked-index.h
@@ -46,6 +46,14 @@
    possible.  This combination should help hide the effort from the
    user to the maximum possible degree.
 
+   There are a number of different objects involved in this process.
+   Most of them are temporary -- they are created to handle different
+   phases of scanning, then discarded when possible.  The "steady
+   state" objects are index itself (cooked_index, below), which holds
+   the entries (cooked_index_entry), and the implementation of the
+   "quick" API (e.g., cooked_index_functions, though there are
+   other variants).
+
    . Main Thread                |       Worker Threads
    ============================================================
    . dwarf2_initialize_objfile
@@ -77,6 +85,7 @@
    .                                        v
    .                              maybe write to index cache
    .                                  state = CACHE_DONE
+   .                                 ~cooked_index_worker
    .
    .
    .   if main thread calls...