update documentation

Author: mileslucas

docs/src/extending.md

@@ -1,23 +1,30 @@
 # Extending Polynomials
 
-The [`AbstractPolynomial`](@ref) type was made to be extended via a rich interface. To implement a new polynomial type, the following methods should be implemented. 
+The [`AbstractPolynomial`](@ref) type was made to be extended via a rich interface. 
 
 ```@docs
 AbstractPolynomial
 ```
 
-| Function | Required | Description |
+To implement a new polynomial type, `P`, the following methods should be implemented. 
+
+!!! note
+    Promotion rules will always coerce towards the [`Polynomial`](@ref) type, so not all methods have to be implemented if you provide a conversion function.
+
+As always, if the default implementation does not work or there are more efficient ways of implementing, feel free to overwrite functions from `common.jl` for your type.
+
+| Function | Required | Notes |
 |----------|:--------:|:------------|
 | Constructor | x | |
-| Type function (`(::MyType)()`) | x | | 
+| Type function (`(::P)(x)`) | x | |
 | `convert(::Polynomial, ...)` | | Not required, but the library is built off the [`Polynomial`](@ref) type, so all operations are guaranteed to work with it. Also consider writing the inverse conversion method. |
-| `domain` | x | |
+| `domain` | x | Should return an  [`AbstractInterval`](https://invenia.github.io/Intervals.jl/stable/#Intervals-1) |
 | `vander` | | Required for [`fit`](@ref) |
 | `companion` | | Required for [`roots`](@ref) |
-| `fromroots` | | |
-| `+` | | | 
-| `-` | | |
-| `*` | | |
-| `divrem` | | |
-
+| `fromroots` | | By default, will form polynomials using `prod(variable(::P) - r)` for reach root `r`|
+| `+(::P, ::P)` | | Addition of polynomials |
+| `-(::P, ::P)` | | Subtraction of polynomials |
+| `*(::P, ::P)` | | Multiplication of polynomials |
+| `divrem` | | Required for [`gcd`](@ref)|
 
+Check out both the [`Polynomial`](@ref) and [`ChebyshevT`](@ref) for examples of this interface being extended!

docs/src/index.md

@@ -132,8 +132,8 @@ the returned roots may be real or complex.
 ```jldoctest
 julia> roots(Polynomial([1, 0, -1]))
 2-element Array{Float64,1}:
- -1.0
   1.0
+ -1.0
 
 julia> roots(Polynomial([1, 0, 1]))
 2-element Array{Complex{Float64},1}:
@@ -142,8 +142,8 @@ julia> roots(Polynomial([1, 0, 1]))
 
 julia> roots(Polynomial([0, 0, 1]))
 2-element Array{Float64,1}:
- -0.0
   0.0
+ -0.0
 ```
 
 ### Fitting arbitrary data

docs/src/polynomials/chebyshev.md

@@ -6,14 +6,24 @@ DocTestSetup = quote
 end
 ```
 
-!!! warning
-  The Chebyshev polynomials are not fully implemented, yet.
-
 ## First Kind
 
 ```@docs
 ChebyshevT
-ChebyshevT
+ChebyshevT()
 ```
 
-## Second Kind
+### Conversion
+
+[`ChebyshevT`](@ref) can be converted to [`Polynomial`](@ref) and vice-versa.
+
+```jldoctest
+julia> c = ChebyshevT([1, 0, 3, 4])
+ChebyshevT([1, 0, 3, 4])
+
+julia> p = convert(Polynomial, c)
+Polynomial(-2 - 12*x + 6*x^2 + 16*x^3)
+
+julia> convert(ChebyshevT, p)
+ChebyshevT([1.0, 0.0, 3.0, 4.0])
+```

docs/src/polynomials/polynomial.md

@@ -8,7 +8,7 @@ end
 
 ```@docs
 Polynomial
-variable
+Polynomial()
 ```
 
 ```@docs

docs/src/reference.md

@@ -21,7 +21,7 @@ degree
 length
 size
 domain
-scale_to_domain
+mapdomain
 chop
 chop!
 truncate
@@ -62,6 +62,9 @@ gcd
 ## Mathematical Function
 
 ```@docs
+zero
+one
+variable
 fromroots
 roots
 derivative
@@ -87,3 +90,23 @@ plot(::AbstractPolynomial, a, b; kwds...)
 ```
 
 will plot the polynomial within the range `[a, b]`.
+
+### Example: The Polynomials.jl logo
+```@example
+using Plots, Polynomials
+xs = range(-1, 1, length=100)
+chebs = [
+  ChebyshevT([0, 1]),
+  ChebyshevT([0, 0, 1]),
+  ChebyshevT([0, 0, 0, 1]),
+  ChebyshevT([0, 0, 0, 0, 1]),
+]
+colors = ["#4063D8", "#389826", "#CB3C33", "#9558B2"]
+plot() # hide
+for (cheb, col) in zip(chebs, colors)
+  plot!(xs, cheb.(xs), c=col, lw=5, label="")
+end
+savefig("chebs.svg"); nothing # hide
+```
+
+![](chebs.svg)

src/polynomials/ChebyshevT.jl

@@ -11,17 +11,14 @@ terms of the given variable `x`. `x` can be a character, symbol, or string.
 # Examples
 
 ```jldoctest
-julia> c = ChebyshevT([1, 0, 3, 4])
+julia> ChebyshevT([1, 0, 3, 4])
 ChebyshevT([1, 0, 3, 4])
 
 julia> ChebyshevT([1, 2, 3, 0], :s)
 ChebyshevT([1, 2, 3])
 
 julia> one(ChebyshevT)
 ChebyshevT([1.0])
-
-julia> convert(Polynomial, c)
-Polynomial(-2 - 12*x + 6*x^2 + 16*x^3)
 ```
 """
 struct ChebyshevT{T <: Number} <: AbstractPolynomial{T}
@@ -65,8 +62,26 @@ domain(::Type{<:ChebyshevT}) = Interval(-1, 1)
     (::ChebyshevT)(x)
 
 Evaluate the Chebyshev polynomial at `x`. If `x` is outside of the domain of [-1, 1], an error will be thrown. The evaluation uses Clenshaw Recursion.
+
+# Examples
+```jldoctest
+julia> c = ChebyshevT([2.5, 1.5, 1.0])
+ChebyshevT([2.5, 1.5, 1.0])
+
+julia> c(0)
+1.5
+
+julia> c.(-1:0.5:1)
+5-element Array{Float64,1}:
+ 2.0
+ 1.25
+ 1.5
+ 2.75
+ 5.0
+```
 """
 function (ch::ChebyshevT{T})(x::S) where {T,S}
+    any(x .∉ domain(ch)) && error("$x outside of domain")
     R = promote_type(T, S)
     length(ch) == 0 && return zero(R)
     length(ch) == 1 && return R(ch[0])

src/polynomials/Polynomial.jl

@@ -42,6 +42,27 @@ end
 domain(::Type{<:Polynomial}) = Interval(-Inf, Inf)
 mapdomain(::Type{<:Polynomial}, x::AbstractArray) = x
 
+"""
+    (p::Polynomial)(x)
+
+Evaluate the polynomial using [Horner's Method](https://en.wikipedia.org/wiki/Horner%27s_method), also known as synthetic division.
+
+# Examples
+```jldoctest
+julia> p = Polynomial([1, 0, 3])
+Polynomial(1 + 3*x^2)
+
+julia> p(0)
+1
+
+julia> p.(0:3)
+4-element Array{Int64,1}:
+  1
+  4
+ 13
+ 28
+```
+"""
 function (p::Polynomial{T})(x::S) where {T,S}
     R = promote_type(T, S)
     length(p) == 0 && return zero(R)