adding some docblocks and @inheritdoc annotations, missing typehint and improving comments