[cfe-commits] r84642 - /cfe/trunk/include/clang-c/Index.h

[Steve Naroff]

Author: snaroff
Date: Tue Oct 20 11:36:34 2009
New Revision: 84642

URL: http://llvm.org/viewvc/llvm-project?rev=84642&view=rev
Log:
Add an example to help claify the process/assumptions...

Modified:
    cfe/trunk/include/clang-c/Index.h

Modified: cfe/trunk/include/clang-c/Index.h
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang-c/Index.h?rev=84642&r1=84641&r2=84642&view=diff

==============================================================================
--- cfe/trunk/include/clang-c/Index.h (original)
+++ cfe/trunk/include/clang-c/Index.h Tue Oct 20 11:36:34 2009
@@ -113,6 +113,30 @@
  *
  * - displayDiagnostics: when non-zero, diagnostics will be output. If zero,
  * diagnostics will be ignored.
+ *
+ * Here is an example:
+ *
+ *   // excludeDeclsFromPCH = 1, displayDiagnostics = 1
+ *   Idx = clang_createIndex(1, 1);
+ *
+ *   // IndexTest.pch was produced with the following command:
+ *   // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
+ *   TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
+ *
+ *   // This will load all the symbols from 'IndexTest.pch'
+ *   clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0);
+ *   clang_disposeTranslationUnit(TU);
+ *
+ *   // This will load all the symbols from 'IndexTest.c', excluding symbols
+ *   // from 'IndexTest.pch'.
+ *   char *args[] = { "-Xclang", "-include-pch=IndexTest.pch", 0 };
+ *   TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args);
+ *   clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0);
+ *   clang_disposeTranslationUnit(TU);
+ *
+ * This process of creating the 'pch', loading it separately, and using it (via
+ * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
+ * (which gives the indexer the same performance benefit as the compiler).
  */
 CXIndex clang_createIndex(int excludeDeclarationsFromPCH,
                           int displayDiagnostics);