updated spec. inline with more documentation