Improve CompletionKind DocC

[rgoldberg]

Improve CompletionKind DocC.

Provide much more precise documentation.

Update documentation to match changes from #726, #734 & #737.

Document shell-specific & shell-version-specific exceptions to standard behavior.

Might be slightly different than the current behavior, but exceptions / bugs will hopefully be fixed soon.

Will revise DocC periodically as completions work progresses.

The custom completion DocC will be vastly updated in my imminent PR that add the proposed 2-index args for custom completions.