DOC: Added documentation to CMake API functions

Improve the documentation of the CMake API, making it clearer what
the expected behavior is, and how the macros/functions should be
used. Also made some very minor whitespace changes in one or two
places for consistency with the rest of the file.

Change-Id: I0293dee3bede73dc0fd91149ae3dd6f62ebd995f
Merge topic 'cmake-documentation' into master

9b076afe DOC: Added documentation to CMake API functions