comment the API a bit

Signed-off-by: Jan Dvořák <mordae@anilinux.org>