From 100b4d58708db521a1f1b24d54ccdd895a006377 Mon Sep 17 00:00:00 2001
From: zymon <s@zymon.org>
Date: Mon, 25 Apr 2022 15:16:06 +0200
Subject: [PATCH] docs for analysis update

Documentation for the function `STFT.analysis` has been created.
---
 src/STFT.jl | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/src/STFT.jl b/src/STFT.jl
index 4e01700..c0351a7 100644
--- a/src/STFT.jl
+++ b/src/STFT.jl
@@ -8,6 +8,70 @@ _fft(x::AbstractMatrix{<:Complex}, d) = fft(x, d)
 
 
 
+"""
+    analysis(x::Vector, w::Vector, L=0, N=length(w)) -> Matrix
+    analysis(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
+
+```math
+\\mathrm{X}[sH, \\omega] =
+    \\sum_{n = -\\infty}^{+\\infty}
+        \\mathrm{w}[n - sH] \\ \\mathrm{x}[n] e^{-j\\omega n},
+```
+
+where ``s`` and ``\\omega`` denotes segment index and angular frequency
+respectively, ``\\mathrm{w}[n]`` is a discrete time-domain signal of analysis
+window, ``H`` is nonnegative integer value that determine number of
+samples between two consecutive signal segments (also known as `hop`).
+
+
+# Parameters
+
+- `x` - An array containing samples of a discrete time-domain signal.
+- `w` - An array containing samples of a discrete time-domain window.
+- `L` - An overlap in samples between two consecutive segments.
+        Default value is `0`.
+- `N` - A number of discrete frequency bins used in DFT computation.
+        Default value is `length(w)`.
+        If `N < length(w)`, then `N=length(w)` is enforced to avoid loss of
+        information.
+
+
+# Returns
+
+- `X` - A complex matrix containing STFT-domain signal.
+
+
+# Note
+
+1. Relation between ``H`` and ``L`` is given as ``H = W - L`` where ``W`` is
+   a length of a window. 
+2. For real-valued (`x isa Real`) input signals function returns matrix is of
+   size `(N÷2+1, S)` where `S` is a number of segments; i.e., one-sided
+   spectrum.
+3. For complex-valued (`x isa Complex`) input signals function returns matrix
+   is of size `(N, S)` where `S` is a number of segments; i.e., two-sided
+   spectrum.
+
+# Examples
+```julia
+import STFT
+
+x = rand(10000) # Generate mock signal
+W = 64          # Window length
+w = ones(W)     # Rectangular analysis window
+H = 10          # Hop
+L = W - H       # Overlap
+
+X = STFT.analysis(x, w, L)  # Analysis
+```
+"""
+function analysis()
+end
+
 function analysis(
     x::AbstractVector{T},
     w::AbstractVector{T},