operations: cleanups of internal API's + improved documentation

Signed-off-by: Peter Soetens <peter@thesourceworks.com>