Make the differences between example 1 and 2 more obvious (API spec)

This addresses #218.