[#539] removed the temporary additional shape in the example
[#539] added documentation for the new response object properties
[#539] added a bunch of utility function to remove shapes

also the `shapes` array is now private, and end-user must used the
provided add/remove function to manage them.