Add a confidence measure for objects detected by detectMultiScale (re-request)

See original pull request https://github.com/Itseez/opencv/pull/961.
The issue: http://code.opencv.org/issues/3067.
**Note:** this commit only touches the C++ interface (and its documentation), Python and Java interfaces should also be updated. Unfortunately, I'm not familiar with them neither as a user, nor as a developer.