add docblocks, correct some typehinting to interfaces, and simplify logic on accept() method