Review/harmonize matfaust/pyfaust circ, anticirc, toeplitz, dct, dst, dft.

wrapper/matlab/+matfaust/anticirc.m

 %==========================================================================================
 %> @brief Returns an anticirculant Faust A defined by the vector c (which is the last column of full(A)).
 %>
+%> @param c: the vector to define the circulant Faust. Its length must be a power of two.
+%>
 %> @b Example
 %>
 %> @code

wrapper/matlab/+matfaust/circ.m

 %==========================================================================================
 %> @brief Returns a circulant Faust C defined by the vector c (which is the first column of full(C)).
 %>
+%> @param c: the vector to define the circulant Faust. Its length must be a power of two.
+%>
 %> @b Example:
 %>
 %> @code

wrapper/matlab/+matfaust/dct.m

 %=========================================
-%> @brief Returns the Direct Cosine Transform (Type II) Faust of order n.
+%> @brief Constructs a Faust implementing the Direct Cosine Transform (Type II) Faust of order n.
 %>
 %> The analytical formula of DCT II used here is:
 %> \f$2 \sum_{i=0}^{n-1} x_i cos \left( {\pi k (2i + 1)} \over {2n} \right)\f$
@@ -9,6 +9,7 @@
 %> @param 'normed',bool: true (by default) to normalize the returned Faust as if Faust.normalize() was called, false otherwise.
 %> @param 'class', str: 'single' or 'double'.
 %>
+%> @retval D the DCT Faust.
 %>
 %> @b Example
 %> @code

wrapper/matlab/+matfaust/dft.m

 %==========================================================================================
 %> @brief Constructs a Faust F implementing the Discrete Fourier Transform (DFT) of order n.
 %>
-%> The factorization algorithm used is Cooley-Tukey (FFT).
-%>
 %> The factorization corresponds to the butterfly structure of the Cooley-Tukey
 %> FFT algorithm. The resulting Faust is complex and has (log2(n)+1) sparse
 %> factors. The log2(n) first has 2 nonzeros per row and per column. The
@@ -16,11 +14,7 @@
 %> @param n: the power of two for a FFT of order n and a factorization in log2(n)+1 factors.
 %> @param 'normed',bool: true (by default) to normalize the returned Faust as if Faust.normalize() was called, false otherwise.
 %> @param 'dev', str: 'gpu or 'cpu' to create the Faust on CPU or GPU ('cpu' by default).
-%> @param 'diag_opt', bool: enable the diagonal optimization of Butterfly and permutation
-%>        factors. Basically, it consists to simplify the product of Faust-vector
-%>        F*x and Faust-matrix F*M to multiplications of factor
-%>        diagonals by the vector x/matrix M. It is particularly more efficient
-%>        when the DFT is multiplied by a matrix.
+%> @param 'diag_opt', bool: if true then the returned Faust is optimized using matfaust.opt_butterfly_faust.
 %>
 %> @retval F the Faust implementing the FFT transform of dimension n.
 %>
@@ -28,8 +22,7 @@
 %> @code
 %> % in a matlab terminal
 %> >> import matfaust.*
-%> >> F = dft(1024) % is equal to
-%> >> F = normalize(dft(1024))
+%> >> F = dft(1024)
 %> @endcode
 %>
 %>
@@ -48,7 +41,12 @@
 %> - FACTOR 9 (complex) SPARSE, size 1024x1024, density 0.00195312, nnz 2048
 %> - FACTOR 10 (complex) SPARSE, size 1024x1024, density 0.000976562, nnz 1024
 %>
-%> @b see also: bitrev_perm, matfaust.wht, matfaust.dct, matfaust.dst, fft, matfaust.rand_butterfly, matfaust.fact.butterfly
+%> @code
+%> >> dft(1024, 'normed', true) % is equiv. to next call
+%> >> normalize(dft(1024, 'normed', false))
+%> @endcode
+%>
+%> @b See @b also: bitrev_perm, matfaust.wht, matfaust.dct, matfaust.dst, fft, matfaust.rand_butterfly, matfaust.fact.butterfly
 %==========================================================================================
 function F = dft(n, varargin)
 	% check n (must be integer > 0)

wrapper/matlab/+matfaust/dst.m

 %=========================================
-%> @brief Returns the Direct Sine Transform (Type II) Faust of order n.
+%> @brief Constructs a Faust implementing the Direct Sine Transform (Type II) Faust of order n.
 %>
-%> The aialytical formula of DST II used here is:
+%> The analytical formula of DST II used here is:
 %> \f$2 \sum_{i=0}^{n-1} x_i sin \left( {\pi (k+1) (2i + 1)} \over {2n} \right)\f$
 %>
 %> @param n: the order of the DST (it must be a power of two).
 %> @param 'dev', str: 'gpu' or 'cpu' to create the Faust on CPU or GPU ('cpu' is the default).
 %> @param 'normed',bool: true (by default) to normalize the returned Faust as if Faust.normalize() was called, false otherwise.
+%> @param 'class', str: 'single' or 'double'.
+%>
+%> @retval D the DST Faust.
 %>
 %> @b Example
 %> @code

wrapper/matlab/+matfaust/toeplitz.m

 %=========================================
-%> @brief Returns a toeplitz Faust whose first column is c and first row r.
+%> @brief Constructs a toeplitz Faust whose first column is c and first row r.
 %>
 %> @b Usage
 %>
 %> &nbsp;&nbsp;&nbsp; @b T = toeplitz(c), T is a symmetric Toeplitz Faust whose the first column is c. <br/>
 %> &nbsp;&nbsp;&nbsp; @b T = toeplitz(c, r), T is a Toeplitz Faust whose the first column is c and the first row is [c(1), r(2:)] <br/>
 %> @param c: the first column of the toeplitz Faust.
-%> @param r: (2nd argument) the first row of the toeplitz Faust. Defaulty r = c.
+%> @param r: (2nd argument) the first row of the toeplitz Faust. Defaulty r = conj(c).
 %> r(1) is ignored, the first row is always [c(1), r(2:)].
 %>
 %>
+%> @retval T the toeplitz Faust.
+%>
 %> @b Example
 %>
 %> @code
@@ -104,7 +106,7 @@ function T = toeplitz(c, varargin)
             error('The second argument must be a vector')
         end
     else
-        r = c; % default r
+        r = conj(c); % default r
     end
     if ~ ismatrix(r) || ~ ismatrix(c) || ~ isnumeric(c) || ~ isnumeric(r)
         error('r and c must be numeric vectors')

wrapper/python/pyfaust.py

@@ -3371,8 +3371,7 @@ def dft(n, normed=True, dev='cpu', diag_opt=False):
         normed: default to True to normalize the DFT Faust as if you called
         Faust.normalize() and False otherwise.
         dev: device to create the Faust on ('cpu' or 'gpu').
-        diag_opt: if True then the returned Faust is optimized using
-        pyfaust.opt_butterfly_faust.
+        diag_opt: if True then the returned Faust is optimized using pyfaust.opt_butterfly_faust.
 
     Returns:
         The Faust implementing the DFT of dimension n.
@@ -3394,7 +3393,7 @@ def dft(n, normed=True, dev='cpu', diag_opt=False):
         - FACTOR 10 (complex) SPARSE, size 1024x1024, density 0.000976562, nnz 1024
 
         >>> dft(1024, normed=True) # is equiv. to next call
-        >>> dft(1024, normed=False).normalize() # which is less optimized though
+        >>> dft(1024, normed=False).normalize()
 
     <b>See also:</b> pyfaust.tools.bitrev, pyfaust.wht, pyfaust.dct, pyfaust.dst, scipy.fft.fft, pyfaust.fact.butterfly, pyfaust.rand_butterfly.
     """
@@ -3428,6 +3427,9 @@ def dct(n, normed=True, dev='cpu', dtype='float64'):
         dev: the device on which the Faust is created.
         dtype: 'float64' (default) or 'float32'.
 
+    Returns:
+        The DCT Faust.
+
     Example:
         >>> from pyfaust import dct
         >>> from scipy.fft import dct as scipy_dct
@@ -3539,6 +3541,9 @@ def dst(n, normed=True, dev='cpu', dtype='float64'):
         dev: the device on which the Faust is created.
         dtype: 'float64' (default) or 'float32'.
 
+    Returns:
+        The DST Faust.
+
     Example:
         >>> from pyfaust import dst
         >>> from scipy.fft import dst as scipy_dst
@@ -3623,7 +3628,11 @@ def dst(n, normed=True, dev='cpu', dtype='float64'):
     return F
 
 def circ(c):
-    """Returns a circulant Faust C defined by the vector c (which is the first column of C.toarray()).
+    """Returns a circulant Faust C defined by the vector c (which is the first
+    column of C.toarray()).
+
+    Args:
+        c: the vector to define the circulant Faust. Its length must be a power of two.
 
     Example:
         >>> from pyfaust import circ
@@ -3696,6 +3705,9 @@ def circ(c):
 def anticirc(c):
     """Returns an anti-circulant Faust A defined by the vector c (which is the last column of A.toarray()).
 
+    Args:
+        c: the vector to define the circulant Faust. Its length must be a power of two.
+
     Example:
         >>> from pyfaust import anticirc
         >>> import numpy as np
@@ -3743,6 +3755,9 @@ def toeplitz(c, r=None):
         np.conjugate(c). r[0] is ignored, the first row is always [c[0],
         r[1:]].
 
+    Returns:
+        The toeplitz Faust.
+
     Example:
         >>> from pyfaust import toeplitz
         >>> import numpy as np