Clarify difference between `params` and `fitted`

[rofinn]

I'm just wondering if someone could clarify what each of these function should return. For example,

1. Should params return trainable and non-trainable parameters? Is params! a multi-argument function which mutates the model parameters, and should it return the set parameters or the updated model?
2. Could fitted be applicable to non-regression problems (e.g., classification, clustering)?

[nalimilan]

Are you really asking for the difference between these functions, or just for their definitions? It seems to me that the difference between params and coef is what needs documenting. See https://github.com/JuliaStats/StatsBase.jl/pull/274 for a discussion when it was introduced in StatsBase. I had proposed the following docstring back then but the PR was merged without it:

Return all parameters of a model. Contrary to coef, this includes parameters other than those corresponding to the effect of independent variables (e.g. in a linear model, those which determine the linear predictor).

Feel free to propose something. I'm not sure what defines trainable parameters though.

Regarding params!, I think the idea is that it stores the parameters in the passed array(s), not that it mutates the model. At least that's how Distributions (which is the only definition currently AFAICT) uses it. This should be documented too. The docstring for it in the original PR was "Write the parameters of a model into preallocated storage.", which we dropped because we don't provide any fallback definition, but we should provide one now I think.

Regarding fitted, I'd say it's fine to define it for classification and clustering. predict could also be used, see https://github.com/JuliaStats/MultivariateStats.jl/issues/190#issuecomment-1091829449.

Cc: @joshday, @ararslan, @andreasnoack

[nalimilan]

See also discussion at https://github.com/JuliaStats/StatsAPI.jl/pull/19 regarding linearpredictor!.