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 1:** this commit will break code that uses the undocumented overload of `detectMultiScale` with `rejectLevels` and `levelWeights`.
**Note 2:** 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.