Merge branch 'jt/decorate-api'

A few structures and variables that are implementation details of
the decorate API have been renamed and then the API got documented
better.

* jt/decorate-api:
decorate: clean up and document API

diff --cc Makefile
Simple merge