perlapi: Add docs for some case-changing macros; clarify others

perlapi: Add docs for some case-changing macros; clarify others

The case changing macros are now almost all documented.  The exception
is toUPPER_LC, which may change in 5.19

In addition the functions in utf8.c that these macros call now refer to
them instead of having their own documentation.  People should really be
using the macros instead of calling the functions directly.  I'm not
deprecating the functions because I can't foresee the need to change
them, so code that uses them should continue to be ok.