Improved docs for extend and promote.

Signed-off-by: Grant Skinner <info@gskinner.com>