Adding more info in docs (#36)

* Adding stable badge for readme

* Expanding on documentation

Co-authored-by: Danny Sharp <[email protected]>

Author: dannys4

README.md

@@ -2,25 +2,23 @@
 ## A library by Danny Sharp
 
 [![Github Action CI](https://github.com/dannys4/FFTA.jl/workflows/CI/badge.svg)](https://github.com/dannys4/FFTA.jl/actions)
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://dannys4.github.io/FFTA.jl/stable/)
 
-This is a *pure Julia* implementation of FFTs, with the goal that this could supplant other FFTs for applications that require odd Julia objects. Currently this supports `AbstractArray{T,N}` where `N` in `{1,2}` (i.e. `AbstractVector` and `AbstractMatrix`). If you're looking for more performance, checkout `FFTW.jl`. Regardless of `T`, `one(::Type{T})` must be defined. Additionally, if `T<:Complex`, then `convert(::Type{T},ComplexF64)` has to be defined and if `T<:Real`, then `convert(::Type{T}, Float64)` has to be defined.
+This is a *pure Julia* implementation of FFTs, with the goal that this could supplant other FFTs for applications that require odd Julia objects. Currently this supports `AbstractArray{T,N}` where `N` in `{1,2}` (i.e. `AbstractVector` and `AbstractMatrix`). If you're looking for more performance, checkout `FFTW.jl`. Regardless of `T`, `one(::Type{T})` must be defined. Additionally, if `T<:Real`, then `convert(::Type{T}, Float64)` has to be defined. Otherwise, `convert(::Type{T},ComplexF64)` must be defined.
 
-Path Forward:
-- Make the code more readable.
-- Use `@inbounds`
-- Use `AbstractFFTs` interface
+Some ideas outside the feature requests in Issues:
+- Make the code more readable
 - Use `StaticArrays` for the workspace in small cases
 - Strictly generate code for certain cases
 - Create a SIMD type for Complex numbers
 - E-Graphs for the call-graph
-- Accelerate dynamic dispatching?
 - Other performance left on the table....
 
 Interface:
-- `fft(x::AbstractVector{<:Union{Real,Complex})`-- Forward FFT
-- `fft(x::AbstractMatrix{<:Union{Real,Complex}})`-- Forward FFT
-- `bfft(x::AbstractVector{<:Union{Real,Complex}})`-- Backward FFT (unscaled inverse FFT)
-- `bfft(x::AbstractMatrix{<:Union{Real,Complex}})`-- Backward FFT (unscaled inverse FFT)
+- `fft(x::AbstractVector)`-- Forward FFT
+- `fft(x::AbstractMatrix})`-- Forward FFT
+- `bfft(x::AbstractVector})`-- Backward FFT (unscaled inverse FFT)
+- `bfft(x::AbstractMatrix})`-- Backward FFT (unscaled inverse FFT)
 
 NOTE: Currently, my C++ code is actually faster than this, so "Fastest Fourier Transform in my Apartment" is a bit of a misnomer.
 

docs/make.jl

@@ -4,6 +4,7 @@ using FFTA
 makedocs(
     sitename = "FFTA",
     format = Documenter.HTML(),
+    pages = ["Development Tools" => "dev.md"],
     modules = [FFTA]
 )
 

docs/src/dev.md

@@ -0,0 +1,11 @@
+Here is the documentation for key parts of the development side of the package.
+```@docs
+CallGraphNode
+CallGraph
+CallGraphNode!
+fft!
+fft_dft!
+fft_pow2!
+fft_pow3!
+fft_pow4!
+```

src/algos.jl

@@ -8,6 +8,20 @@ function (g::CallGraph{T})(out::AbstractVector{T}, in::AbstractVector{U}, start_
     fft!(out, in, start_out, start_in, v, t, g, idx)
 end
 
+"""
+$(TYPEDSIGNATURES)
+Cooley-Tukey composite FFT, with a pre-computed call graph
+
+# Arguments
+`out`: Output vector
+`in`: Input vector
+`start_out`: Index of the first element of the output vector
+`start_in`: Index of the first element of the input vector
+`d`: Direction of the transform
+`g`: Call graph for this transform
+`idx`: Index of the current transform in the call graph
+
+"""
 function fft!(out::AbstractVector{T}, in::AbstractVector{U}, start_out::Int, start_in::Int, d::Direction, ::CompositeFFT, g::CallGraph{T}, idx::Int) where {T,U}
     root = g[idx]
     left_idx = idx + root.left
@@ -38,6 +52,21 @@ function fft!(out::AbstractVector{T}, in::AbstractVector{U}, start_out::Int, sta
     end
 end
 
+"""
+$(TYPEDSIGNATURES)
+Discrete Fourier Transform, O(N^2) algorithm, in place.
+
+# Arguments
+`out`: Output vector
+`in`: Input vector
+`N`: Size of the transform
+`start_out`: Index of the first element of the output vector
+`stride_out`: Stride of the output vector
+`start_in`: Index of the first element of the input vector
+`stride_in`: Stride of the input vector
+`d`: Direction of the transform
+
+"""
 function fft_dft!(out::AbstractVector{T}, in::AbstractVector{T}, N::Int, start_out::Int, stride_out::Int, start_in::Int, stride_in::Int, d::Direction) where {T}
     tmp = in[start_in]
     @inbounds for j in 1:N-1
@@ -91,7 +120,18 @@ function fft!(out::AbstractVector{T}, in::AbstractVector{U}, start_out::Int, sta
 end
 
 """
-Power of 2 FFT in place
+$(TYPEDSIGNATURES)
+Power of 2 FFT, in place
+
+# Arguments
+`out`: Output vector
+`in`: Input vector
+`N`: Size of the transform
+`start_out`: Index of the first element of the output vector
+`stride_out`: Stride of the output vector
+`start_in`: Index of the first element of the input vector
+`stride_in`: Stride of the input vector
+`d`: Direction of the transform
 
 """
 function fft_pow2!(out::AbstractVector{T}, in::AbstractVector{U}, N::Int, start_out::Int, stride_out::Int, start_in::Int, stride_in::Int, d::Direction) where {T, U}
@@ -126,7 +166,18 @@ function fft!(out::AbstractVector{T}, in::AbstractVector{U}, start_out::Int, sta
 end
 
 """
-Power of 4 FFT in place
+$(TYPEDSIGNATURES)
+Power of 4 FFT, in place
+
+# Arguments
+`out`: Output vector
+`in`: Input vector
+`N`: Size of the transform
+`start_out`: Index of the first element of the output vector
+`stride_out`: Stride of the output vector
+`start_in`: Index of the first element of the input vector
+`stride_in`: Stride of the input vector
+`d`: Direction of the transform
 
 """
 function fft_pow4!(out::AbstractVector{T}, in::AbstractVector{U}, N::Int, start_out::Int, stride_out::Int, start_in::Int, stride_in::Int, d::Direction) where {T, U}
@@ -179,6 +230,23 @@ function fft!(out::AbstractVector{T}, in::AbstractVector{U}, start_out::Int, sta
     fft_pow4!(out, in, N, start_out, s_out, start_in, s_in, d)
 end
 
+"""
+$(TYPEDSIGNATURES)
+Power of 3 FFT, in place
+
+# Arguments
+out: Output vector
+in: Input vector
+N: Size of the transform
+start_out: Index of the first element of the output vector
+stride_out: Stride of the output vector
+start_in: Index of the first element of the input vector
+stride_in: Stride of the input vector
+d: Direction of the transform
+plus120: Depending on direction, perform either ±120° rotation
+minus120: Depending on direction, perform either ∓120° rotation
+
+"""
 function fft_pow3!(out::AbstractVector{T}, in::AbstractVector{U}, N::Int, start_out::Int, stride_out::Int, start_in::Int, stride_in::Int, d::Direction, plus120::T, minus120::T) where {T, U}
     if N == 3
         @muladd out[start_out + 0]            = in[start_in] + in[start_in + stride_in]          + in[start_in + 2*stride_in]

src/callgraph.jl

@@ -23,15 +23,11 @@ $(TYPEDSIGNATURES)
 Node of a call graph
 
 # Arguments
-`left::Int`- Offset to the left child node
-`right::Int`- Offset to the right child node
-`type::AbstractFFTType`- Object representing the type of FFT
-`sz::Int`- Size of this FFT
-
-# Examples
-```julia
-julia> CallGraphNode(0, 0, Pow2FFT(), 8)
-```
+`left`: Offset to the left child node
+`right`: Offset to the right child node
+`type`: Object representing the type of FFT
+`sz`: Size of this FFT
+
 """
 struct CallGraphNode
     left::Int
@@ -47,13 +43,9 @@ $(TYPEDSIGNATURES)
 Object representing a graph of FFT Calls
 
 # Arguments
-`nodes::Vector{CallGraphNode}`- Nodes keeping track of the graph
-`workspace::Vector{Vector{T}}`- Preallocated Workspace
+`nodes`: Nodes keeping track of the graph
+`workspace`: Preallocated Workspace
 
-# Examples
-```julia
-julia> CallGraph{ComplexF64}(CallGraphNode[], Vector{T}[])
-```
 """
 struct CallGraph{T<:Complex}
     nodes::Vector{CallGraphNode}
@@ -96,7 +88,18 @@ function _ispow24(N::Int)
     return N < 3 ? Pow24(N) : nothing
 end
 
-# Recursively instantiate a set of `CallGraphNode`s
+"""
+$(TYPEDSIGNATURES)
+Recursively instantiate a set of `CallGraphNode`s
+
+# Arguments
+`nodes`: A vector (which gets expanded) of `CallGraphNode`s
+`N`: The size of the FFT
+`workspace`: A vector (which gets expanded) of preallocated workspaces
+`s_in`: The stride of the input
+`s_out`: The stride of the output
+
+"""
 function CallGraphNode!(nodes::Vector{CallGraphNode}, N::Int, workspace::Vector{Vector{T}}, s_in::Int, s_out::Int)::Int where {T}
     if iseven(N)
         pow = _ispow24(N)
@@ -141,7 +144,11 @@ function CallGraphNode!(nodes::Vector{CallGraphNode}, N::Int, workspace::Vector{
     return 1 + left_len + right_len
 end
 
-# Instantiate a CallGraph from a number `N`
+"""
+$(TYPEDSIGNATURES)
+Instantiate a CallGraph from a number `N`
+
+"""
 function CallGraph{T}(N::Int) where {T}
     nodes = CallGraphNode[]
     workspace = Vector{Vector{T}}()