Cleanup and document SIL memory behavior APIs.

This is code that I am fairly familiar with but it still took a day of
investigation to figure out how it is supposed to be used now in the
presence of bridging.

This primarily involved ruling out the possibity that the mid-level
Swift APIs could at some point call into the lower-level C++ APIs.

The biggest problem was that AliasAnalysis::getMemoryBehaviorOfInst()
was declared as a public interface, and it's name indicates that it
computes the memory behavior. But it is just a wrapper around a Swift
API and never actually calls into any of the C++ logic that is
responsible for computing memory behavior!

include/swift/SIL/SILNodes.def

@@ -137,8 +137,13 @@
 ///   NAME is the name of the instruction in SIL assembly.
 ///   The argument will be a bare identifier, not a string literal.
 ///
-///   MEMBEHAVIOR is an enum value that reflects the memory behavior of
-///   the instruction.
+///   MEMBEHAVIOR is an enum value that reflects the memory behavior of the
+///   instruction. It is only used in the implementation of
+///   SILInstruction::getMemoryBehavior(). Memory behavior is relative, so
+///   whenever possible, clients should instead use
+///   AliasAnalysis::computeMemoryBehavior(SILInstruction, SILValue) which only
+///   defaults to SILInstruction::getMemoryBehavior() when AliasAnalysis cannot
+///   disambiguate the instruction's effects from the value of interest.
 ///
 ///   MAYRELEASE indicates whether the execution of the
 ///   instruction may result in memory being released.