From: Argyrios Kyrtzidis <akyrtzi@gmail.com>
Date: Wed, 16 Nov 2011 08:59:00 +0000 (+0000)
Subject: [libclang] Add a comment in lazyCreateDiags to explain why the check and reset of
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c88e58c0db75e7b5f9f14da0a255a0be01acf877;p=clang

[libclang] Add a comment in lazyCreateDiags to explain why the check and reset of
diagnostic set is necessary.

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

diff --git a/tools/libclang/CIndexDiagnostic.cpp b/tools/libclang/CIndexDiagnostic.cpp
index 50641fad1c..de0e8d4c8f 100644
--- a/tools/libclang/CIndexDiagnostic.cpp
+++ b/tools/libclang/CIndexDiagnostic.cpp
@@ -44,6 +44,23 @@ static CXDiagnosticSetImpl *lazyCreateDiags(CXTranslationUnit TU,
   ASTUnit *AU = static_cast<ASTUnit *>(TU->TUData);
 
   if (TU->Diagnostics && checkIfChanged) {
+    // In normal use, ASTUnit's diagnostics should not change unless we reparse.
+    // Currently they can only change by using the internal testing flag
+    // '-error-on-deserialized-decl' which will error during deserialization of
+    // a declaration. What will happen is:
+    //
+    //  -c-index-test gets a CXTranslationUnit
+    //  -checks the diagnostics, the diagnostics set is lazily created,
+    //     no errors are reported
+    //  -later does an operation, like annotation of tokens, that triggers
+    //     -error-on-deserialized-decl, that will emit a diagnostic error,
+    //     that ASTUnit will catch and add to its stored diagnostics vector.
+    //  -c-index-test wants to check whether an error occurred after performing
+    //     the operation but can only query the lazily created set.
+    //
+    // We check here if a new diagnostic was appended since the last time the
+    // diagnostic set was created, in which case we reset it.
+
     CXDiagnosticSetImpl *
       Set = static_cast<CXDiagnosticSetImpl*>(TU->Diagnostics);
     if (AU->stored_diag_size() != Set->getNumDiagnostics()) {