moved my changes around so that effect on internal API is minimised; added comments