From 0e1f17badfa1086f98404a56d32f2f282f6a0eb6 Mon Sep 17 00:00:00 2001
From: zymon <s@zymon.org>
Date: Tue, 10 May 2022 17:34:51 +0200
Subject: [PATCH] Aliases for `analysis` and `synthesis`.

Function `stft` as an alias for `analysis`.
Function `istft` as an alias for `synthesis`.
`stft` and `istft` are exported.
Documentation update.
---
 Project.toml |  6 +++---
 README.md    |  2 +-
 src/STFT.jl  | 56 +++++++++++++++++++++++++++++++++++++++++++---------
 3 files changed, 51 insertions(+), 13 deletions(-)

diff --git a/Project.toml b/Project.toml
index a7ced3e..ca202e7 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,7 +1,7 @@
 name = "STFT"
 uuid = "58bb99bf-048b-48b7-93e7-1cbf3ee61509"
 authors = ["Szymon M. Woźniak"]
-version = "0.1.0"
+version = "1.0.0"
 
 [deps]
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
@@ -9,5 +9,5 @@ FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
 
 [compat]
 
-FFTW = "1.4.6"
-julia = "1.7"
+FFTW = "1.4"
+julia = "1.6"
diff --git a/README.md b/README.md
index 7215aa1..e05823c 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 
 [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://docs.zymon.org/STFT.jl/)
 
-`STFT.jl` is a julia package implementing Short-Time Fourier Transform routines.
+`STFT.jl` is a Julia package implementing Short-Time Fourier Transform (STFT) routines.
 It provides signal analysis (time-domain signal to STFT-domain signal; stft)
 and signal synthesis (STFT-domain siganl to time-domain signal; istft).
 
diff --git a/src/STFT.jl b/src/STFT.jl
index 9a6e65b..bc40eb2 100644
--- a/src/STFT.jl
+++ b/src/STFT.jl
@@ -2,16 +2,20 @@ module STFT
 
 using FFTW
 
+export stft, istft
 
 _fft(x::AbstractMatrix{<:Real}, d) = rfft(x, d)
 _fft(x::AbstractMatrix{<:Complex}, d) = fft(x, d)
 
 
 
-"""
+doc_analysis = """
     analysis(x::Vector, w::Vector, L=0, N=length(w)) -> Matrix
     analysis(x::Array{Vector}, w::Vector, L=0, N=length(w)) -> Array{Matrix}
 
+    stft(x::Vector, w::Vector, L=0, N=length(w)) -> Matrix
+    stft(x::Array{Vector}, w::Vector, L=0, N=length(w)) -> Array{Matrix}
+
 
 Analyse discrete time-domain signal ``\\mathrm{x}[n]``
 using Short-Time Fourier Transform given by
@@ -68,9 +72,26 @@ L = W - H       # Overlap
 
 X = STFT.analysis(x, w, L)  # Analysis
 ```
+
+```julia
+using STFT
+
+x = rand(100)   # Generate mock signal
+W = 64          # Window length
+w = ones(W)     # Rectangular analysis window
+H = 4           # Hop
+L = W - H       # Overlap
+
+X  = stft(x, w, L)  # Analysis
+```
+
 """
-function analysis()
-end
+
+"$doc_analysis"
+function analysis() end
+
+"$doc_analysis"
+stft(x, w, L=0, N=length(w)) = analysis(x, w, L, N)
 
 function analysis(
     x::AbstractVector{T},
@@ -102,10 +123,11 @@ end
 
 
 
-
-"""
+doc_synthesis = """
     synthesis(X::Matrix, w::Vector, L=0, N=length(w)) -> Vector
 
+    istft(X::Matrix, w::Vector, L=0, N=length(w)) -> Vector
+
 Syntesise discrete time-domain signal ``y[n]`` from STFT-domain signal
 ``Y_w[sH, n]``.
 An arbitrary STFT-domain signal ``Y_w[sH, n]``, in general, is not a valid STFT
@@ -163,6 +185,20 @@ X  = STFT.analysis(x, w, L)  # Analysis
 xr = STFT.synthesis(X, w, L) # Synthesis
 ```
 
+```julia
+using STFT
+
+x = rand(100)   # Generate mock signal
+W = 64          # Window length
+w = ones(W)     # Rectangular analysis window
+H = 4           # Hop
+L = W - H       # Overlap
+
+X  = stft(x, w, L)  # Analysis
+xr = istft(X, w, L) # Synthesis
+```
+
+
 # References
 1. D. Griffin and J. Lim, “Signal estimation from modified short-time
    Fourier transform,” IEEE Transactions on Acoustics, Speech, and
@@ -171,8 +207,12 @@ xr = STFT.synthesis(X, w, L) # Synthesis
    \\[[IEEE Xplore](https://ieeexplore.ieee.org/abstract/document/1164317),
    [pdf](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.331.7151&rep=rep1&type=pdf)\\]
 """
-function synthesis()
-end
+
+"$doc_synthesis"
+function synthesis() end
+
+"$doc_synthesis"
+isftf(X, w, L=0, N=length(w)) = synthesis(X, w, L, N)
 
 function synthesis(
     X::AbstractMatrix{<:Complex},
@@ -200,6 +240,4 @@ function synthesis(
     xn ./ xd # Normalize
 end
 
-
-
 end # module