+;;;
+;;; Comment from Eric Marsden:
+;;;
+;;; This file contains code that attempts to identify symbols in a
+;;; CMUCL image that are stale. For example, the package descriptions
+;;; in src/code/package.lisp can get out of sync with the source code,
+;;; leading to symbols that are exported without being used anywhere.
+;;;
+;;; The routines work by walking all the objects allocated in a heap
+;;; image (using the function VM::MAP-ALLOCATED-OBJECTS). For each
+;;; object of type symbol, it scans the entire heap for objects that
+;;; reference that symbol. If it finds no references, or if there is
+;;; only one reference that looks like it is likely from the internals
+;;; of a package-related datastructure, the name of the symbol and its
+;;; package is displayed.
+;;;
+;;; The "references to that symbol" are found using the function
+;;; SB-VM::MAP-REFERENCING-OBJECTS. Consider for example a function
+;;; that uses the value of a symbol. The code-object for that function
+;;; contains a reference to the symbol, so that a call to SYMBOL-VALUE
+;;; can be made at runtime. The data structures corresponding to a
+;;; package must maintain a list of its exported an imported symbols.
+;;; They contain a hashtable, which contains a vector, which contains
+;;; symbols. So all exported symbols will have at least one
+;;; referencing object: a vector related to some package.
+;;;
+;;; Limitations: these routines may provide a number of false
+;;; positives (symbols that are not actually stale). There are also a
+;;; number of PCL-related symbols that are displayed, but probably
+;;; used internally by PCL. Moral: the output of these routines must
+;;; be checked carefully before going on a code deletion spree.