refactored out duplicate code and added documentation about inconsistencies between platforms