[clang] [llvm] [clang] Add/enhance documentation for some important classes. (PR #109795)

[Alexandre Ganea via cfe-commits]

================
@@ -648,18 +648,54 @@ class InBeforeInTUCacheEntry {
 /// instances.
 using ModuleBuildStack = ArrayRef<std::pair<std::string, FullSourceLoc>>;
 
-/// This class handles loading and caching of source files into memory.
+/// The SourceManager describes the compiler's view of source code.
 ///
-/// This object owns the MemoryBuffer objects for all of the loaded
-/// files and assigns unique FileID's for each unique \#include chain.
+/// This includes:
+///   - sources before preprocessing: raw code from disk
+///   - code after preprocessing e.g. expanded from an `assert()` macro
+///   - the relationship between the two, e.g. where the `assert()` was written
 ///
-/// The SourceManager can be queried for information about SourceLocation
-/// objects, turning them into either spelling or expansion locations. Spelling
-/// locations represent where the bytes corresponding to a token came from and
-/// expansion locations represent where the location is in the user's view. In
-/// the case of a macro expansion, for example, the spelling location indicates
-/// where the expanded token came from and the expansion location specifies
-/// where it was expanded.
+/// SourceManager is designed to represent this information compactly. 
+/// AST nodes hold SourceLocations pointing at tokens that were parsed,
+/// so that diagnostics can point to relevant source code (including macros).
+/// A SourceLocation is a 32-bit integer, and is only meaningful together with
+/// the SourceManager which maintains the tables needed to decode it.
+///
+/// The SourceManager sits above the FileManager, which reads source files and
+/// exposes them as FileEntrys.
+/// SourceManager does not generally know about tokens or AST nodes, the lexer
+/// and parser are layered above SourceManager.
+/// 
+/// ====== SourceLocations, FileIDs, and SLocEntrys =======
+///
+/// A SourceLocation can point at any byte of code. Rather than store
+/// (file, offset) pairs, it is a single offset into a buffer of all files
----------------
aganea wrote:

it is a single offset into a **virtual** buffer of all files?

https://github.com/llvm/llvm-project/pull/109795