add docstrings for Jacobi and Legendre (#215)

docs/make.jl

@@ -1,5 +1,9 @@
 using Documenter, ClassicalOrthogonalPolynomials
 
+DocMeta.setdocmeta!(ClassicalOrthogonalPolynomials,
+    :DocTestSetup,
+    :(using ClassicalOrthogonalPolynomials))
+
 makedocs(
     modules = [ClassicalOrthogonalPolynomials],
     sitename="ClassicalOrthogonalPolynomials.jl",

docs/src/index.md

@@ -126,17 +126,15 @@ U\T
 
 ```@docs
 ClassicalOrthogonalPolynomials.Chebyshev
-```
-```@docs
 ClassicalOrthogonalPolynomials.chebyshevt
-```
-```@docs
 ClassicalOrthogonalPolynomials.chebyshevu
 ```
 ```@docs
+ClassicalOrthogonalPolynomials.Legendre
 ClassicalOrthogonalPolynomials.legendrep
 ```
 ```@docs
+ClassicalOrthogonalPolynomials.Jacobi
 ClassicalOrthogonalPolynomials.jacobip
 ```
 ```@docs
@@ -147,8 +145,6 @@ ClassicalOrthogonalPolynomials.hermiteh
 ```
 
 
-
-
 ### Weights
 
 ```@docs
@@ -161,7 +157,9 @@ ClassicalOrthogonalPolynomials.HermiteWeight
 ClassicalOrthogonalPolynomials.Weighted
 ```
 ```@docs
+ClassicalOrthogonalPolynomials.LegendreWeight
 ClassicalOrthogonalPolynomials.ChebyshevWeight
+ClassicalOrthogonalPolynomials.JacobiWeight
 ```
 ```@docs
 ClassicalOrthogonalPolynomials.LaguerreWeight
@@ -170,6 +168,13 @@ ClassicalOrthogonalPolynomials.LaguerreWeight
 ClassicalOrthogonalPolynomials.HalfWeighted
 ```
 
+### Affine-mapped
+```@docs
+ClassicalOrthogonalPolynomials.legendre
+ClassicalOrthogonalPolynomials.jacobi
+ClassicalOrthogonalPolynomials.legendreweight
+ClassicalOrthogonalPolynomials.jacobiweight
+```
 
 ### Recurrences
 
@@ -190,32 +195,22 @@ ClassicalOrthogonalPolynomials.recurrencecoefficients
 ```
 
 
-
 ### Internal
 
 ```@docs
-ClassicalOrthogonalPolynomials.ShuffledIR2HC
-```
-```@docs
-ClassicalOrthogonalPolynomials.ShuffledR2HC
-```
-```@docs
+ClassicalOrthogonalPolynomials.ShuffledFFT
 ClassicalOrthogonalPolynomials.ShuffledIFFT
+ClassicalOrthogonalPolynomials.ShuffledR2HC
+ClassicalOrthogonalPolynomials.ShuffledIR2HC
 ```
 ```@docs
 ClassicalOrthogonalPolynomials.qr_jacobimatrix
-```
-```@docs
-ClassicalOrthogonalPolynomials.MappedOPLayout
-```
-```@docs
 ClassicalOrthogonalPolynomials.cholesky_jacobimatrix
 ```
 ```@docs
 ClassicalOrthogonalPolynomials.AbstractNormalizedOPLayout
-```
-```@docs
-ClassicalOrthogonalPolynomials.ShuffledFFT
+ClassicalOrthogonalPolynomials.MappedOPLayout
+ClassicalOrthogonalPolynomials.WeightedOPLayout
 ```
 ```@docs
 ClassicalOrthogonalPolynomials.legendre_grammatrix
@@ -224,9 +219,6 @@ ClassicalOrthogonalPolynomials.legendre_grammatrix
 ClassicalOrthogonalPolynomials.weightedgrammatrix
 ```
 ```@docs
-ClassicalOrthogonalPolynomials.WeightedOPLayout
-```
-```@docs
 ClassicalOrthogonalPolynomials.interlace!
 ```
 ```@docs

src/classical/jacobi.jl

@@ -21,13 +21,48 @@ broadcasted(::LazyQuasiArrayStyle{1}, ::typeof(sqrt), w::AbstractJacobiWeight) =
 broadcasted(::LazyQuasiArrayStyle{1}, ::typeof(Base.literal_pow), ::Base.RefValue{typeof(^)}, w::AbstractJacobiWeight, ::Base.RefValue{Val{k}}) where k =
     JacobiWeight(k * w.a, k * w.b)
 
+"""
+    JacobiWeight{T}(a,b)
+    JacobiWeight(a,b)
+
+The quasi-vector representing the Jacobi weight function ``(1-x)^a (1+x)^b`` on ``[-1,1]``. See also [`jacobiweight`](@ref) and [`Jacobi`](@ref).
+# Examples
+```jldoctest
+julia> J=JacobiWeight(1.0,1.0)
+(1-x)^1.0 * (1+x)^1.0 on -1..1
+
+julia> J[0.5]
+0.75
+
+julia> axes(J)
+(Inclusion(-1.0 .. 1.0 (Chebyshev)),)
+```
+"""
 struct JacobiWeight{T} <: AbstractJacobiWeight{T}
     a::T
     b::T
     JacobiWeight{T}(a, b) where T = new{T}(convert(T,a), convert(T,b))
 end
 
 JacobiWeight(a::V, b::T) where {T,V} = JacobiWeight{promote_type(T,V)}(a,b)
+
+"""
+    jacobiweight(a,b, d::AbstractInterval)
+
+The [`JacobiWeight`](@ref) affine-mapped to interval `d`.
+
+# Examples
+```jldoctest
+julia> J = jacobiweight(1, 1, 0..1)
+(1-x)^1 * (1+x)^1 on -1..1 affine mapped to 0 .. 1
+
+julia> axes(J)
+(Inclusion(0 .. 1),)
+
+julia> J[0.5]
+1.0
+```
+"""
 jacobiweight(a,b, d::AbstractInterval{T}) where T = JacobiWeight(a,b)[affine(d,ChebyshevInterval{T}())]
 
 AbstractQuasiArray{T}(w::JacobiWeight) where T = JacobiWeight{T}(w.a, w.b)
@@ -92,7 +127,41 @@ include("legendre.jl")
 singularitiesbroadcast(::typeof(*), ::LegendreWeight, b::AbstractJacobiWeight) = b
 singularitiesbroadcast(::typeof(*), a::AbstractJacobiWeight, ::LegendreWeight) = a
 
-
+"""
+    Jacobi{T}(a,b)
+    Jacobi(a,b)
+
+The quasi-matrix representing Jacobi polynomials, where the first axes represents the interval and the second axes represents the polynomial index (starting from 1). See also [`jacobi`](@ref), [`jacobip`](@ref) and [`JacobiWeight`](@ref).
+
+The eltype, when not specified, will be converted to a floating point data type.
+# Examples
+```jldoctest
+julia> J=Jacobi(0,0) # The eltype will be converted to float
+Jacobi(0.0, 0.0)
+
+julia> axes(J)
+(Inclusion(-1.0 .. 1.0 (Chebyshev)), OneToInf())
+
+julia> J[0,:] # Values of polynomials at x=0
+ℵ₀-element view(::Jacobi{Float64}, 0.0, :) with eltype Float64 with indices OneToInf():
+  1.0
+  0.0
+ -0.5
+ -0.0
+  0.375
+  0.0
+ -0.3125
+ -0.0
+  0.2734375
+  0.0
+  ⋮
+
+julia> J0=J[:,1]; # J0 is the first Jacobi polynomial which is constant.
+
+julia> J0[0],J0[0.5]
+(1.0, 1.0)
+```
+"""
 struct Jacobi{T} <: AbstractJacobi{T}
     a::T
     b::T
@@ -104,7 +173,34 @@ Jacobi(a::V, b::T) where {T,V} = Jacobi{float(promote_type(T,V))}(a, b)
 AbstractQuasiArray{T}(w::Jacobi) where T = Jacobi{T}(w.a, w.b)
 AbstractQuasiMatrix{T}(w::Jacobi) where T = Jacobi{T}(w.a, w.b)
 
-
+"""
+    jacobi(a,b, d::AbstractInterval)
+
+The [`Jacobi`](@ref) polynomials affine-mapped to interval `d`.
+
+# Examples
+```jldoctest
+julia> J = jacobi(1, 1, 0..1)
+Jacobi(1.0, 1.0) affine mapped to 0 .. 1
+
+julia> axes(J)
+(Inclusion(0 .. 1), OneToInf())
+
+julia> J[0,:]
+ℵ₀-element view(::Jacobi{Float64}, -1.0, :) with eltype Float64 with indices OneToInf():
+   1.0
+  -2.0
+   3.0
+  -4.0
+   5.0
+  -6.0
+   7.0
+  -8.0
+   9.0
+ -10.0
+   ⋮
+```
+"""
 jacobi(a,b) = Jacobi(a,b)
 jacobi(a,b, d::AbstractInterval{T}) where T = Jacobi{float(promote_type(eltype(a),eltype(b),T))}(a,b)[affine(d,ChebyshevInterval{T}()), :]
 

src/classical/legendre.jl

@@ -1,5 +1,40 @@
+"""
+    LegendreWeight{T}()
+    LegendreWeight()
+
+The quasi-vector representing the Legendre weight function (const 1) on [-1,1]. See also [`legendreweight`](@ref) and [`Legendre`](@ref).
+# Examples
+```jldoctest
+julia> w = LegendreWeight()
+LegendreWeight{Float64}()
+
+julia> w[0.5]
+1.0
+
+julia> axes(w)
+(Inclusion(-1.0 .. 1.0 (Chebyshev)),)
+```
+"""
 struct LegendreWeight{T} <: AbstractJacobiWeight{T} end
 LegendreWeight() = LegendreWeight{Float64}()
+
+"""
+    legendreweight(d::AbstractInterval)
+
+The [`LegendreWeight`](@ref) affine-mapped to interval `d`.
+
+# Examples
+```jldoctest
+julia> w = legendreweight(0..1)
+LegendreWeight{Float64}() affine mapped to 0 .. 1
+
+julia> axes(w)
+(Inclusion(0 .. 1),)
+
+julia> w[0]
+1.0
+```
+"""
 legendreweight(d::AbstractInterval{T}) where T = LegendreWeight{float(T)}()[affine(d,ChebyshevInterval{T}())]
 
 AbstractQuasiArray{T}(::LegendreWeight) where T = LegendreWeight{T}()
@@ -46,6 +81,41 @@ singularities(::AbstractFillLayout, P) = LegendreWeight{eltype(P)}()
 basis_singularities(::LegendreWeight{T}) where T = Legendre{T}()
 basis_singularities(v::SubQuasiArray) = view(basis_singularities(parent(v)), parentindices(v)[1], :)
 
+"""
+    Legendre{T=Float64}(a,b)
+
+The quasi-matrix representing Legendre polynomials, where the first axes represents the interval and the second axes represents the polynomial index (starting from 1). See also [`legendre`](@ref), [`legendrep`](@ref), [`LegendreWeight`](@ref) and [`Jacobi`](@ref).
+# Examples
+```jldoctest
+julia> P = Legendre()
+Legendre()
+
+julia> typeof(P) # default eltype
+Legendre{Float64}
+
+julia> axes(P)
+(Inclusion(-1.0 .. 1.0 (Chebyshev)), OneToInf())
+
+julia> P[0,:] # Values of polynomials at x=0
+ℵ₀-element view(::Legendre{Float64}, 0.0, :) with eltype Float64 with indices OneToInf():
+  1.0
+  0.0
+ -0.5
+ -0.0
+  0.375
+  0.0
+ -0.3125
+ -0.0
+  0.2734375
+  0.0
+  ⋮
+
+julia> P₀=P[:,1]; # P₀ is the first Legendre polynomial which is constant.
+
+julia> P₀[0],P₀[0.5]
+(1.0, 1.0)
+```
+"""
 struct Legendre{T} <: AbstractJacobi{T} end
 Legendre() = Legendre{Float64}()
 
@@ -57,6 +127,34 @@ weighted(P::Normalized{<:Any,<:Legendre}) = P
 weighted(P::SubQuasiArray{<:Any,2,<:Legendre}) = P
 weighted(P::SubQuasiArray{<:Any,2,<:Normalized{<:Any,<:Legendre}}) = P
 
+"""
+    legendre(d::AbstractInterval)
+
+The [`Legendre`](@ref) polynomials affine-mapped to interval `d`.
+
+# Examples
+```jldoctest
+julia> P = legendre(0..1)
+Legendre() affine mapped to 0 .. 1
+
+julia> axes(P)
+(Inclusion(0 .. 1), OneToInf())
+
+julia> P[0.5,:]
+ℵ₀-element view(::Legendre{Float64}, 0.0, :) with eltype Float64 with indices OneToInf():
+  1.0
+  0.0
+ -0.5
+ -0.0
+  0.375
+  0.0
+ -0.3125
+ -0.0
+  0.2734375
+  0.0
+  ⋮
+```
+"""
 legendre() = Legendre()
 legendre(d::AbstractInterval{T}) where T = Legendre{float(T)}()[affine(d,ChebyshevInterval{T}()), :]
 legendre(d::ChebyshevInterval{T}) where T = Legendre{float(T)}()