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 --combined Makefile
index 80e0674d6f1d52a3bf93d115f3d41cd86e111e08,df52cc1c3907ad33c23aed9eae508ac84488a659..32c170687c8ff573f7bde3f0914b86202ad4e54e
--- 1/Makefile
--- 2/Makefile
+++ b/Makefile
@@@ -651,6 -651,7 +651,7 @@@ TEST_PROGRAMS_NEED_X += test-dump-cache
  TEST_PROGRAMS_NEED_X += test-dump-fsmonitor
  TEST_PROGRAMS_NEED_X += test-dump-split-index
  TEST_PROGRAMS_NEED_X += test-dump-untracked-cache
+ TEST_PROGRAMS_NEED_X += test-example-decorate
  TEST_PROGRAMS_NEED_X += test-fake-ssh
  TEST_PROGRAMS_NEED_X += test-genrandom
  TEST_PROGRAMS_NEED_X += test-hashmap
@@@ -759,7 -760,6 +760,7 @@@ LIB_OBJS += branch.
  LIB_OBJS += bulk-checkin.o
  LIB_OBJS += bundle.o
  LIB_OBJS += cache-tree.o
 +LIB_OBJS += checkout.o
  LIB_OBJS += color.o
  LIB_OBJS += column.o
  LIB_OBJS += combine-diff.o
@@@ -811,8 -811,6 +812,8 @@@ LIB_OBJS += levenshtein.
  LIB_OBJS += line-log.o
  LIB_OBJS += line-range.o
  LIB_OBJS += list-objects.o
 +LIB_OBJS += list-objects-filter.o
 +LIB_OBJS += list-objects-filter-options.o
  LIB_OBJS += ll-merge.o
  LIB_OBJS += lockfile.o
  LIB_OBJS += log-tree.o