[silgen] Add a doxygen doc above FormalEvaluationScope.

[gottesmm]

[silgen] Add a doxygen doc above FormalEvaluationScope.

I added a general description, but more importantly, I added a note about a
quirk in our current implementation that existed before my current changes.

Specifically:

All formal access contain a pointer to a cleanup in the normal cleanup
stack. This is to ensure that when SILGen calls Cleanups.emitBranchAndCleanups
(and other special cleanup code along error edges), writebacks are properly
created. What is key to notice is that all of these cleanup emission types are
non-destructive. Contrast this with normal scope popping. In such a case, the
scope pop is destructive. This means that any pointers from the formal access to
the cleanup stack is now invalid.

rdar://30955427

---

As a side note, in a future PR I am going to add some asserts so that if this issue comes up, we blow up when creating the formal access, rather than when we pop the formal evaluation scope. It makes it easier to solve these problems.

Perhaps, we should consider completely splitting these stacks... Hmmm...

[gottesmm]

If we completely split the cleanup stacks, I would hide in CleanupManager the ability to perform those non-destructive cleanups to ensure I find all of them and reroute those uses through a higher level construct that would handle both FormalAccess and LexicalAccess cleanups.

[gottesmm]

@swift-ci Please smoke test and merge