Update pyfaust/matfaust API doc, in particular for Faust addition and substraction.

wrapper/matlab/+matfaust/@Faust/Faust.m

@@ -68,8 +68,6 @@
 %> - compute the real and imaginary parts of a Faust,
 %> - perform elementwise operations between two Fausts (e.g. elementwise
 %> multiplication).
-%> In particular, the addition F+G is undefined for Faust objects (so
-%> far).
 %> - reshape,
 %> - invert.
 %>
@@ -248,6 +246,24 @@ classdef Faust
 		end
 
 		%======================================================================
+		%> @brief Plus
+		%>
+		%===
+		%> This function overloads a Matlab built-in function.
+		%>
+		%>
+		%> @b Usage
+		%>
+		%> &nbsp;&nbsp;&nbsp; @b plus(F,G) or F+G adds two Faust together, sizes must be compatible.<br/>
+		%> &nbsp;&nbsp;&nbsp; @b plus(F,A) or F+A adds a Faust and a matrix A, sizes must be compatible.<br/>
+		%> &nbsp;&nbsp;&nbsp; @b plus(F,s) or F+s, with s being a scalar, such that full(F+s) == full(F)+s.<br/>
+		%>
+		%> @param F (first arg.) The Faust object.
+		%> @param G, A, s,… (2nd to n-th args) The variables to add to F; Fausts, matrices or scalars.
+		%>
+		%> @retval S: the sum as a Faust object.
+		%>
+		%> <p>@b See @b also Faust.minus
 		%======================================================================
 		function F = plus(varargin)
 			import matfaust.Faust
@@ -286,6 +302,24 @@ classdef Faust
 		end
 
 		%======================================================================
+		%> @brief Minus
+		%>
+		%===
+		%> This function overloads a Matlab built-in function.
+		%>
+		%>
+		%> @b Usage
+		%>
+		%> &nbsp;&nbsp;&nbsp; @b minus(F,G) or F-G substracts the Faust G from F, sizes must be compatible.<br/>
+		%> &nbsp;&nbsp;&nbsp; @b minus(F,A) or F-A substracts a matrix A from F, sizes must be compatible.<br/>
+		%> &nbsp;&nbsp;&nbsp; @b minus(F,s) or F-s substracts a scalar s from F, such that full(F-s) == full(F)-s.<br/>
+		%>
+		%> @param F (first arg.) The Faust object.
+		%> @param G, A, s,… (2nd to n-th args) The variables to substract from F; Fausts, matrices or scalars.
+		%>
+		%> @retval M: the difference as a Faust object.
+		%>
+		%> <p>@b See @b also Faust.plus
 		%======================================================================
 		function M = minus(varargin)
 			M = varargin{1}
@@ -300,7 +334,7 @@ classdef Faust
 		%===
 		%> @b Usage
 		%>
-		%> &nbsp;&nbsp;&nbsp; G = F/s is the division of the Faust F by the scalar s.<br/>
+		%> &nbsp;&nbsp;&nbsp; G = F/s is the division of the Faust F by the scalar s, such that full(F)/s == full(F/s)<br/>
 		%> &nbsp;&nbsp;&nbsp; G = MRDIVIDE(F,s) is called for the syntax 'F / s' when s is a scalar.
 		%>
 		%> @param F The Faust object to divide.
@@ -308,6 +342,7 @@ classdef Faust
 		%>
 		%> @retval G: the division result as a Faust object.
 		%>
+		%> <p>@b See @b also Faust.mtimes
 		%======================================================================
 		function G = mrdivide(F,s)
 			if(~ isscalar(s))

wrapper/python/pyfaust.py

@@ -84,9 +84,7 @@ class Faust:
     Other notable limitations are that one cannot:
         - compute the real and imaginary parts of a Faust,
         - perform elementwise operations between two Fausts (e.g. elementwise
-        multiplication).
-        In particular, the addition F+G is undefined for Faust objects (so
-        far).
+        multiplication),
         - reshape.
 
     Primarily for convenience and test purposes, a Faust can be converted into
@@ -415,7 +413,21 @@ class Faust:
         print(F.__repr__())
         #F.m_faust.display()
 
-    def __add__(F,*args):
+    def __add__(F, *args):
+        """
+        Sums F to one or a sequence of variables. Faust objects, arrays or scalars.
+
+        This method overloads the Python function/operator +.
+
+        Args:
+            *args: the list of variables to sum all together with F. These can
+            be: Faust objects, arrays (and scipy.sparse.csr_matrix) or scalars.
+            Faust and arrays/matrices must be of compatible size.
+
+        Returns: the sum as a Faust object.
+
+        <b/>See also Faust.__sub__
+        """
         for i in range(0,len(args)):
             G = args[i]
             if(isinstance(G,Faust)):
@@ -445,6 +457,21 @@ class Faust:
         return F
 
     def __sub__(F,*args):
+        """
+        Substracts from F one or a sequence of variables. Faust objects, arrays or scalars.
+
+        This method overloads the Python function/operator -.
+
+        Args:
+            *args: the list of variables to compute the difference with F. These can
+            be: Faust objects, arrays (and scipy.sparse.csr_matrix) or scalars.
+            Faust and arrays/matrices must be of compatible size.
+
+        Returns: the difference as a Faust object.
+
+        <b/>See also Faust.__add__
+        """
+
         nargs = []
         for arg in args:
             nargs += [ arg*-1 ]
@@ -454,11 +481,17 @@ class Faust:
         """
         Divides F by the scalar s.
 
+        This method overloads the Python function/operator `/' (whether s is a
+        float or an integer).
+
         Args:
-            - F: the Faust object.
-            - s: the scalar to divide the Faust object with.
+        F: the Faust object.
+        s: the scalar to divide the Faust object with.
+
+        Returns:
+            the division result as a Faust object.
 
-        Returns: the division result as a Faust object.
+        <b/> See also Faust.__mul__
         """
         if(isinstance(s, float) or isinstance(s, np.complex) or isinstance(s,
                                                                            int)):
@@ -539,7 +572,7 @@ class Faust:
             >>> # H is a Faust because F and G are
             >>> F_times_two = F*2
 
-        <b/>See also Faust.__init__, Faust.rcg
+        <b/>See also Faust.__init__, Faust.rcg, Faust.__mul__
         """
         if(isinstance(A, Faust)):
             if(F.shape[1] != A.shape[0]): raise ValueError("The dimensions of "