+ DWARF, etc) belong somewhere else.
+
+ The basic way this module is used is as follows:
+
+ buildsym_init ();
+ cleanups = make_cleanup (really_free_pendings, NULL);
+ cust = start_symtab (...);
+ ... read debug info ...
+ cust = end_symtab (...);
+ do_cleanups (cleanups);
+
+ The compunit symtab pointer ("cust") is returned from both start_symtab
+ and end_symtab to simplify the debug info readers.
+
+ There are minor variations on this, e.g., dwarf2read.c splits end_symtab
+ into two calls: end_symtab_get_static_block, end_symtab_from_static_block,
+ but all debug info readers follow this basic flow.
+
+ Reading DWARF Type Units is another variation:
+
+ buildsym_init ();
+ cleanups = make_cleanup (really_free_pendings, NULL);
+ cust = start_symtab (...);
+ ... read debug info ...
+ cust = end_expandable_symtab (...);
+ do_cleanups (cleanups);
+
+ And then reading subsequent Type Units within the containing "Comp Unit"
+ will use a second flow:
+
+ buildsym_init ();
+ cleanups = make_cleanup (really_free_pendings, NULL);
+ cust = restart_symtab (...);
+ ... read debug info ...
+ cust = augment_type_symtab (...);
+ do_cleanups (cleanups);
+
+ dbxread.c and xcoffread.c use another variation:
+
+ buildsym_init ();
+ cleanups = make_cleanup (really_free_pendings, NULL);
+ cust = start_symtab (...);
+ ... read debug info ...
+ cust = end_symtab (...);
+ ... start_symtab + read + end_symtab repeated ...
+ do_cleanups (cleanups);
+*/