improved internal docs and ordering of spec312