documentation for unconstrain_pars, constrain_pars is insufficient and misleading

Summary:

Currently the documentation for the unconstrain_pars and constrain_pars functions is lacking and even misleading

Description:

• there are no usage examples
• the argument descriptions do not sufficiently describe the form of the required inputs
• there are some important subtleties that are not described in the documentation and that can lead to incorrect usage. For example, unconstrain_pars(object, pars), returns the same exact thing even if the parameter values provided in pars are permuted. This is particularly confusing because the values are unnamed and it is not documented at all.

Reproducible Steps:

Here's an example of the last bullet point above:

fit <- stan_demo("eight_schools")
pars <- list(mu = 0, tau = 2, theta = rep(1.5, 8))
unconstrain_pars(fit, pars)
unconstrain_pars(fit, rev(pars))

Those two calls to unconstrain_pars return the same thing even though the parameters are passed in the opposite order. The both return an unnamed vector:

 [1] 0.0000000 1.5000000 1.5000000 1.5000000 1.5000000 1.5000000
 [7] 1.5000000 1.5000000 1.5000000 0.6931472

This seems like a recipe for a lot of confusion. At a minimum we need to document this (I can do that), but I wonder if we should also be naming the values returned by unconstrain_pars? Why are the values returned by constrain_pars named but not those returned by unconstrain_pars?

RStan Version:

2.12.1

Start with the existing documentation for unconstrain_pars and constrain_pars, then review the reproducible eight_schools example in the issue. Document the required input forms, provide usage examples, and explain the behavior of permuted unnamed parameters and returned names. Done means the documented behavior and the naming question are clear to users.