add docblock, rm unused, rename for clarity