Refactor, docblocks and fixes for #3282