[api] Improve documentation for API handle types.

Add a few explanations to the documentation several methods and classes,
in particular Local, MaybeLocal, the HandleScopes.

Drive-by-fix: turn a few regular comments into documentation comments.

BUG=

Review-Url: https://codereview.chromium.org/2783843002
Cr-Commit-Position: refs/heads/master@{#44243}