JavaDocs and code overhaul / simplification + updated docs and TODO with more reasonings