Document the value casting API changes.

After changing the way several value inheritance hierarchies (TypeLoc,
CFGelement, ProgramPoint and SVal) handle casting, this documentation describes
how 3rd party code may need to be updated to compile with the new APIs.

As suggested by Sean Silva on cfe-dev.

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

diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst
index 5435ce50f60dc3355e356c28be5b4c070a62250b..eeb9998392765acbfd0a3988041985317f34745c 100644 (file)
--- a/docs/ReleaseNotes.rst
+++ b/docs/ReleaseNotes.rst
@@ -98,6 +98,18 @@ These are major API changes that have happened since the 3.2 release of
 Clang. If upgrading an external codebase that uses Clang as a library,
 this section should help get you past the largest hurdles of upgrading.
 
+Value Casting
+^^^^^^^^^^^^^
+
+Certain type hierarchies (TypeLoc, CFGElement, ProgramPoint, and SVal) were
+misusing the llvm::cast machinery to perform undefined operations. Their APIs
+have been changed to use two member function templates that return values
+instead of pointers or references - "T castAs" and "Optional<T> getAs" (in the
+case of the TypeLoc hierarchy the latter is "T getAs" and you can use the
+boolean testability of a TypeLoc (or its 'validity') to verify that the cast
+succeeded). Essentially all previous 'cast' usage should be replaced with
+'castAs' and 'dyn_cast' should be replaced with 'getAs'.
+ 
 API change 1
 ^^^^^^^^^^^^