add REST documentation for principals module

As of this afternoon I think I've gone through all the modules and followed up. (Though there are enough comments that I've almost certainly missed a few.) The three areas that I've postponed and would be easier to do all at once are:

* Figure out how to effectively document models that are unions of other models (or, said another way, how to document responses and parameters that can be one of several different models).
* Add status codes for HTTP error responses.
* Reorder form parameters so required parameters precede optional ones.