Add a block comment explaining how the different source locations work

including some source examples.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@139295 91177308-0d34-0410-b5e6-96231b3b80d8

diff --git a/include/clang/Basic/SourceManager.h b/include/clang/Basic/SourceManager.h
index af5f76969a9744ebf2c5aaf88b0e7b4092acf2be..d1d2a916810aeccabd4d4686bfd7ccc0c0e505d4 100644 (file)
--- a/include/clang/Basic/SourceManager.h
+++ b/include/clang/Basic/SourceManager.h
@@ -38,6 +38,22 @@ class LangOptions;
 class ASTWriter;
 class ASTReader;
   
+/// There are three different types of locations in a file: a spelling
+/// location, an expansion location, and a presumed location.
+///
+/// Given an example of:
+/// #define min(x, y) x < y ? x : y
+///
+/// and then later on a use of min:
+/// return min(a, b);
+/// #line 17
+///
+/// The expansion location is the line in the source code where the macro
+/// was expanded (the return statement), the spelling location is the
+/// location in the source where the macro was originally defined,
+/// and the presumed location is where the line directive states that
+/// the line is 17, or any other line.
+
 /// SrcMgr - Public enums and private classes that are part of the
 /// SourceManager implementation.
 ///