Cleanup docs (#708)

nalimilan · web-flow · commit 6138a11faa8b · 2021-08-25T16:31:55.000+02:00
Ensure that all exported methods are included in the manual, so that
we can enable strict=true, which ensures that doctests pass.
Update doctests to latest Julia version.
diff --git a/docs/make.jl b/docs/make.jl
@@ -10,7 +10,6 @@ makedocs(
     modules = [StatsBase],
     pages = ["index.md",
              "weights.md",
-             "means.md",
              "scalarstats.md",
              "robust.md",
              "deviation.md",
@@ -23,7 +22,9 @@ makedocs(
              "multivariate.md",
              "misc.md",
              "statmodels.md",
-             "transformations.md"]
+             "transformations.md"],
+    strict=true,
+    checkdocs=:exports
 )
 
 deploydocs(
diff --git a/docs/src/counts.md b/docs/src/counts.md
@@ -15,5 +15,5 @@ addcounts!(r::AbstractArray, x::StatsBase.IntegerArray, levels::StatsBase.IntUni
 ```@docs
 countmap
 proportionmap
-addcounts!{T}(cm::Dict{T}, x::AbstractArray{T})
+addcounts!(cm::Dict, x::Any)
 ```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -12,7 +12,7 @@ end
 
 
 ```@contents
-Pages = ["weights.md", "means.md", "scalarstats.md", "robust.md", "deviation.md", "cov.md", "counts.md", "ranking.md", "sampling.md", "empirical.md", "signalcorr.md", "misc.md", "statmodels.md", "transformations.md"]
+Pages = ["weights.md", "scalarstats.md", "robust.md", "deviation.md", "cov.md", "counts.md", "ranking.md", "sampling.md", "empirical.md", "signalcorr.md", "misc.md", "statmodels.md", "transformations.md"]
 Depth = 2
 ```
 
diff --git a/docs/src/means.md b/docs/src/means.md
diff --git a/docs/src/robust.md b/docs/src/robust.md
@@ -2,6 +2,8 @@
 
 ```@docs
 trim
+trim!
 winsor
+winsor!
 trimvar
 ```
diff --git a/docs/src/sampling.md b/docs/src/sampling.md
@@ -7,6 +7,8 @@ The package provides functions for sampling from a given population (with or wit
 ```@docs
 sample
 sample!
+wsample
+wsample!
 ```
 
 ## Algorithms
diff --git a/docs/src/scalarstats.md b/docs/src/scalarstats.md
@@ -2,6 +2,27 @@
 
 The package implements functions for computing various statistics over an array of scalar real numbers.
 
+## Weighted sum and mean
+
+```@docs
+sum
+sum!
+wsum
+wsum!
+mean
+mean!
+```
+
+## Means
+
+The package provides functions to compute means of different kinds.
+
+```@docs
+geomean
+harmmean
+genmean
+```
+
 ## Moments
 
 ```@docs
@@ -21,6 +42,7 @@ span
 variation
 sem
 mad
+mad!
 ```
 
 ## Z-scores
diff --git a/docs/src/statmodels.md b/docs/src/statmodels.md
@@ -24,6 +24,7 @@ loglikelihood
 mss
 nobs
 nulldeviance
+nullloglikelihood
 r2
 rss
 score
@@ -47,3 +48,8 @@ predict
 predict!
 residuals
 ```
+
+An exception type is provided to signal convergence failures during model estimation:
+```@docs
+ConvergenceException
+```
diff --git a/docs/src/transformations.md b/docs/src/transformations.md
@@ -40,11 +40,17 @@ in a single call.
 fit(::Type{UnitRangeTransform}, X::AbstractArray{<:Real,2}; unit::Bool=true)
 ```
 
-## Additional Methods
+## Methods
 ```@docs
 StatsBase.transform
 StatsBase.transform!
 StatsBase.reconstruct
 StatsBase.reconstruct!
 standardize
 ```
+
+## Types
+```@docs
+UnitRangeTransform
+ZScoreTransform
+```
diff --git a/docs/src/weights.md b/docs/src/weights.md
@@ -54,7 +54,7 @@ w = uweights(Float64, 3)
 
 ### `Weights`
 
-The `Weights` type describes a generic weights vector which does not support all operations possible for `FrequencyWeights`, `AnalyticWeights` and `ProbabilityWeights`.
+The `Weights` type describes a generic weights vector which does not support all operations possible for `FrequencyWeights`, `AnalyticWeights`, `ProbabilityWeights` and `UnitWeights`.
 
 ```julia
 w = Weights([1., 2., 3.])
@@ -142,10 +142,12 @@ The following constructors are provided:
 AnalyticWeights
 FrequencyWeights
 ProbabilityWeights
+UnitWeights
 Weights
 aweights
 fweights
 pweights
 eweights
+uweights
 weights
 ```
diff --git a/src/hist.jl b/src/hist.jl
@@ -137,15 +137,15 @@ Histograms can be fitted to data using the `fit` method.
 julia> using StatsBase
 
 julia> fit(Histogram, [2.],  1:3, closed=:left)
-Histogram{Int64,1,Tuple{UnitRange{Int64}}}
+Histogram{Int64, 1, Tuple{UnitRange{Int64}}}
 edges:
   1:3
 weights: [0, 1]
 closed: left
 isdensity: false
 
 julia> fit(Histogram, [2.],  1:3, closed=:right)
-Histogram{Int64,1,Tuple{UnitRange{Int64}}}
+Histogram{Int64, 1, Tuple{UnitRange{Int64}}}
 edges:
   1:3
 weights: [1, 0]
diff --git a/src/misc.jl b/src/misc.jl
@@ -126,7 +126,7 @@ it will be dense (default).
 julia> using StatsBase
 
 julia> indicatormat([1 2 2], 2)
-2×3 Array{Bool,2}:
+2×3 Matrix{Bool}:
  1  0  0
  0  1  1
 ```
diff --git a/src/transformations.jl b/src/transformations.jl
@@ -93,15 +93,15 @@ and return a `ZScoreTransform` transformation object.
 julia> using StatsBase
 
 julia> X = [0.0 -0.5 0.5; 0.0 1.0 2.0]
-2×3 Array{Float64,2}:
+2×3 Matrix{Float64}:
  0.0  -0.5  0.5
  0.0   1.0  2.0
 
 julia> dt = fit(ZScoreTransform, X, dims=2)
-ZScoreTransform{Float64}(2, 2, [0.0, 1.0], [0.5, 1.0])
+ZScoreTransform{Float64, Vector{Float64}}(2, 2, [0.0, 1.0], [0.5, 1.0])
 
 julia> StatsBase.transform(dt, X)
-2×3 Array{Float64,2}:
+2×3 Matrix{Float64}:
   0.0  -1.0  1.0
  -1.0   0.0  1.0
 ```
@@ -247,15 +247,15 @@ and return a `UnitRangeTransform` transformation object.
 julia> using StatsBase
 
 julia> X = [0.0 -0.5 0.5; 0.0 1.0 2.0]
-2×3 Array{Float64,2}:
+2×3 Matrix{Float64}:
  0.0  -0.5  0.5
  0.0   1.0  2.0
 
 julia> dt = fit(UnitRangeTransform, X, dims=2)
-UnitRangeTransform{Float64}(2, 2, true, [-0.5, 0.0], [1.0, 0.5])
+UnitRangeTransform{Float64, Vector{Float64}}(2, 2, true, [-0.5, 0.0], [1.0, 0.5])
 
 julia> StatsBase.transform(dt, X)
-2×3 Array{Float64,2}:
+2×3 Matrix{Float64}:
  0.5  0.0  1.0
  0.0  0.5  1.0
 ```
@@ -353,12 +353,12 @@ end
 julia> using StatsBase
 
 julia> standardize(ZScoreTransform, [0.0 -0.5 0.5; 0.0 1.0 2.0], dims=2)
-2×3 Array{Float64,2}:
+2×3 Matrix{Float64}:
   0.0  -1.0  1.0
  -1.0   0.0  1.0
 
 julia> standardize(UnitRangeTransform, [0.0 -0.5 0.5; 0.0 1.0 2.0], dims=2)
-2×3 Array{Float64,2}:
+2×3 Matrix{Float64}:
  0.5  0.0  1.0
  0.0  0.5  1.0
 ```
diff --git a/src/weights.jl b/src/weights.jl
@@ -536,8 +536,9 @@ wsumtype(::Type{T}, ::Type{W}) where {T,W} = typeof(zero(T) * zero(W) + zero(T)
 wsumtype(::Type{T}, ::Type{T}) where {T<:BlasReal} = T
 
 """
-    wsum!(R, A, w, dim; init=true)
-
+    wsum!(R::AbstractArray, A::AbstractArray,
+          w::AbstractWeights{<:Real}, dim::Int;
+          init::Bool=true)
 Compute the weighted sum of `A` with weights `w` over the dimension `dim` and store
 the result in `R`. If `init=false`, the sum is added to `R` rather than starting
 from zero.
@@ -562,9 +563,24 @@ end
 
 ## extended sum! and wsum
 
+"""
+    sum!(R::AbstractArray, A::AbstractArray,
+         w::AbstractWeights{<:Real}, dim::Int;
+         init::Bool=true)
+
+Compute the weighted sum of `A` with weights `w` over the dimension `dim` and store
+the result in `R`. If `init=false`, the sum is added to `R` rather than starting
+from zero.
+"""
 Base.sum!(R::AbstractArray, A::AbstractArray, w::AbstractWeights{<:Real}, dim::Int; init::Bool=true) =
     wsum!(R, A, w, dim; init=init)
 
+"""
+    sum(v::AbstractArray, w::AbstractVector{<:Real}; [dims])
+
+Compute the weighted sum of an array `v` with weights `w`,
+optionally over the dimension `dims`.
+"""
 Base.sum(A::AbstractArray, w::AbstractWeights{<:Real}; dims::Union{Colon,Int}=:) =
     wsum(A, w, dims)
 
@@ -576,11 +592,6 @@ end
 
 ##### Weighted means #####
 
-"""
-    wmean(v, w::AbstractVector)
-
-Compute the weighted mean of an array `v` with weights `w`.
-"""
 function wmean(v::AbstractArray{<:Number}, w::AbstractVector)
     Base.depwarn("wmean is deprecated, use mean(v, weights(w)) instead.", :wmean)
     mean(v, weights(w))

-Original file line number
+Diff line change
 ```@docs
 trim
 +trim!
 winsor
 +winsor!
 trimvar
 ```