add some comments
update example spec to reflect new format