adding more clear documentation

Like suggested in http://code.opencv.org/issues/3933
This is an attempt into making this work out.

WORK IN PROGRESS, DO NOT MERGE YET