Bad docstring for MvNormal

[KronosTheLate]

The current docstrint for MvNormal starts like this:

help?> MvNormal
search: MvNormal MvNormalCanon MvNormalKnownCov MvLogNormal AbstractMvNormal

  MvNormal


  Generally, users don't have to worry about these internal details.

  We provide a common constructor MvNormal, which will construct a distribution of       
  appropriate type depending on the input arguments.

As a user, this is not very helpful. Where are "these internals details" that I do not have to worry about, that are referred to? Where should I go to find documentation about multivariate normal distributions? Constructors, how to interpret the inputs, sampling from such a distribution etc.

[ForceBru]

Constructors, how to interpret the inputs

This is covered in the very next documentation entries:

help?> MvNormal
search: MvNormal MvNormalCanon MvNormalKnownCov MvLogNormal AbstractMvNormal

  MvNormal

  Generally, users don't have to worry about these internal details.

  We provide a common constructor MvNormal, which will construct a
  distribution of appropriate type depending on the input arguments.

  ────────────────────────────────────────────────────────────────────────────

  MvNormal(μ::AbstractVector{<:Real}, Σ::AbstractMatrix{<:Real})

  Construct a multivariate normal distribution with mean μ and covariance
  matrix Σ.

  ────────────────────────────────────────────────────────────────────────────

  MvNormal(Σ::AbstractMatrix{<:Real})

  Construct a multivariate normal distribution with zero mean and covariance
  matrix Σ.

julia> 

So you call MvNormal(mu, sigma) to "Construct a multivariate normal distribution with mean μ and covariance matrix Σ", where mu is a vector and sigma is a matrix, as per the constructor type signature.

---

Where should I go to find documentation about multivariate normal distributions?

• https://juliastats.org/Distributions.jl/latest/multivariate for multivariate distributions in general;
• https://juliastats.org/Distributions.jl/latest/multivariate/#Distributions.AbstractMvNormal for multivariate normal.

The usual suggestion to list all methods that work on a given type (MvNormal in your case) is to call methodswith(MvNormal). It works, but the output is just a list of methods that isn't particularly legible: it doesn't include any documentation, for example - you'll have to manually do ?some_method. I think currently the best method to read the documentation is to visit the documentation site for the particular package.

[KronosTheLate]

Right. But the start of the docstring feels like it is sort of pushing me away from using it as a reference. And the rest of the docstrings are short, without examples. It is not wrong in any sense, but it is not nearly as helpful as I feel it could be.

What is even the point of the start of the docstring? Why is it there, and should it not be removed?