implement, document and test the 'instantiate' decorator

@mcdonc has already given his blessing for this, see #11.

Please can someone with appropriate privs merge this?