From: Argyrios Kyrtzidis <akyrtzi@gmail.com>
Date: Fri, 4 May 2012 18:33:19 +0000 (+0000)
Subject: Add more comments for Lexer::makeFileCharRange.
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=95da18142abeec5099dedc50d6f418917bd6167d;p=clang

Add more comments for Lexer::makeFileCharRange.

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

diff --git a/include/clang/Lex/Lexer.h b/include/clang/Lex/Lexer.h
index 04bcead6d4..4878123d1b 100644
--- a/include/clang/Lex/Lexer.h
+++ b/include/clang/Lex/Lexer.h
@@ -335,6 +335,28 @@ public:
   ///
   /// Returns a null range if a part of the range resides inside a macro
   /// expansion or the range does not reside on the same FileID.
+  ///
+  /// This function is trying to deal with macros and return a range based on
+  /// file locations. The cases where it can successfully handle macros are:
+  ///
+  /// -begin or end range lies at the start or end of a macro expansion, in
+  ///  which case the location will be set to the expansion point, e.g:
+  ///    #define M 1 2
+  ///    a M
+  /// If you have a range [a, 2] (where 2 came from the macro), the function
+  /// will return a range for "a M"
+  /// if you have range [a, 1], the function will fail because the range
+  /// overlaps with only a part of the macro
+  ///
+  /// -The macro is a function macro and the range can be mapped to the macro
+  ///  arguments, e.g:
+  ///    #define M 1 2
+  ///    #define FM(x) x
+  ///    FM(a b M)
+  /// if you have range [b, 2], the function will return the file range "b M"
+  /// inside the macro arguments.
+  /// if you have range [a, 2], the function will return the file range
+  /// "FM(a b M)" since the range includes all of the macro expansion.
   static CharSourceRange makeFileCharRange(CharSourceRange Range,
                                            const SourceManager &SM,
                                            const LangOptions &LangOpts);