Repository: chainer/chainer

Issue:
No documents on operators supported by Variable
Some python operators are supported by `Variable` (implemented in `functions/math/basic_math.py`) and some are not, but it is not clear from the current chainer documents. It would be nice if some documents are provided on supported operators.



Discussion:
For example, maybe users cannot know `abs()` can be applied to `Variable` from the current documents.


Resolving patch:
diff --git a/chainer/functions/math/basic_math.py b/chainer/functions/math/basic_math.py
--- a/chainer/functions/math/basic_math.py
+++ b/chainer/functions/math/basic_math.py
@@ -62,8 +62,13 @@ def backward(self, x, gy):
         return utils.force_array(-gy[0]),
 
 
-def neg(x):  # -x
-    return Neg()(x)
+def neg(self):  # -x
+    """Element-wise negation.
+
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
+    return Neg()(self)
 
 
 class Absolute(function.Function):
@@ -90,8 +95,13 @@ def backward_gpu(self, x, gy):
         return gx0,
 
 
-def absolute(x):
-    return Absolute()(x)
+def absolute(self):
+    """Element-wise absolute.
+
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
+    return Absolute()(self)
 
 
 class Add(function.Function):
@@ -135,11 +145,16 @@ def backward(self, x, gy):
         return gy[0],
 
 
-def add(lhs, rhs):  # lhs + rhs
+def add(self, rhs):  # lhs + rhs
+    """Element-wise addition.
+
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
     if isinstance(rhs, variable.Variable):
-        return Add()(lhs, rhs)
+        return Add()(self, rhs)
     _check_constant_type(rhs)
-    return AddConstant(rhs)(lhs)
+    return AddConstant(rhs)(self)
 
 
 class Sub(function.Function):
@@ -162,11 +177,17 @@ def backward(self, x, gy):
         return gy[0], utils.force_array(-gy[0])
 
 
-def sub(lhs, rhs):  # lhs - rhs
+def sub(self, rhs):  # lhs - rhs
+    """Element-wise subtraction.
+
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
+
     if isinstance(rhs, variable.Variable):
-        return Sub()(lhs, rhs)
+        return Sub()(self, rhs)
     _check_constant_type(rhs)
-    return AddConstant(-rhs)(lhs)
+    return AddConstant(-rhs)(self)
 
 
 class SubFromConstant(function.Function):
@@ -189,11 +210,16 @@ def backward(self, x, gy):
         return utils.force_array(-gy[0]),
 
 
-def rsub(lhs, rhs):  # rhs - lhs
+def rsub(self, rhs):  # rhs - lhs
+    """Element-wise subtraction.
+
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
     if isinstance(rhs, variable.Variable):
-        return Sub()(rhs, lhs)
+        return Sub()(rhs, self)
     _check_constant_type(rhs)
-    return SubFromConstant(rhs)(lhs)
+    return SubFromConstant(rhs)(self)
 
 
 class Mul(function.Function):
@@ -238,11 +264,17 @@ def backward(self, x, gy):
         return utils.force_array(value * gy[0]),
 
 
-def mul(lhs, rhs):  # lhs * rhs
+def mul(self, rhs):  # lhs * rhs
+    """Element-wise multiplication.
+
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
+
     if isinstance(rhs, variable.Variable):
-        return Mul()(lhs, rhs)
+        return Mul()(self, rhs)
     _check_constant_type(rhs)
-    return MulConstant(rhs)(lhs)
+    return MulConstant(rhs)(self)
 
 
 class Div(function.Function):
@@ -276,11 +308,17 @@ def backward_gpu(self, x, gy):
             ''', 'div_bwd')(x[0], x[1], gy[0])
 
 
-def div(lhs, rhs):  # lhs / rhs
+def div(self, rhs):  # lhs / rhs
+    """Element-wise division
+
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
+
     if isinstance(rhs, variable.Variable):
-        return Div()(lhs, rhs)
+        return Div()(self, rhs)
     _check_constant_type(rhs)
-    return MulConstant(1. / rhs)(lhs)
+    return MulConstant(1. / rhs)(self)
 
 
 class DivFromConstant(function.Function):
@@ -312,11 +350,17 @@ def backward_gpu(self, x, gy):
         return gx,
 
 
-def rdiv(lhs, rhs):  # rhs / lhs
+def rdiv(self, rhs):  # rhs / lhs
+    """Element-wise division.
+
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
+
     if isinstance(rhs, variable.Variable):
-        return Div()(rhs, lhs)
+        return Div()(rhs, self)
     _check_constant_type(rhs)
-    return DivFromConstant(rhs)(lhs)
+    return DivFromConstant(rhs)(self)
 
 
 class PowVarVar(function.Function):
@@ -386,11 +430,17 @@ def backward_gpu(self, x, gy):
         return gx,
 
 
-def pow(lhs, rhs):  # lhs ** rhs
+def pow(self, rhs):  # lhs ** rhs
+    """Element-wise power function.
+
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
+
     if isinstance(rhs, variable.Variable):
-        return PowVarVar()(lhs, rhs)
+        return PowVarVar()(self, rhs)
     _check_constant_type(rhs)
-    return PowVarConst(rhs)(lhs)
+    return PowVarConst(rhs)(self)
 
 
 class PowConstVar(function.Function):
@@ -425,11 +475,17 @@ def backward_gpu(self, x, gy):
         return gx,
 
 
-def rpow(lhs, rhs):  # rhs ** lhs
+def rpow(self, rhs):  # rhs ** lhs
+    """Element-wise power function.
+
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
+
     if isinstance(rhs, variable.Variable):
-        return PowVarVar()(rhs, lhs)
+        return PowVarVar()(rhs, self)
     _check_constant_type(rhs)
-    return PowConstVar(rhs)(lhs)
+    return PowConstVar(rhs)(self)
 
 
 class MatMulVarVar(_matmul.MatMul):
@@ -509,18 +565,30 @@ def backward(self, x, gy):
         return gx1,
 
 
-def matmul(lhs, rhs):  # lhs @ rhs
+def matmul(self, rhs):  # lhs @ rhs
+    """Matrix multiplication.
+
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
+
     if isinstance(rhs, variable.Variable):
-        return MatMulVarVar()(lhs, rhs)
+        return MatMulVarVar()(self, rhs)
     _check_constant_type(rhs)
-    return MatMulVarConst(rhs)(lhs)
+    return MatMulVarConst(rhs)(self)
+
+
+def rmatmul(self, rhs):  # rhs @ lhs
+    """Matrix multiplication.
 
+    Returns:
+        ~chainer.Variable: Output variable.
+    """
 
-def rmatmul(lhs, rhs):  # rhs @ lhs
     if isinstance(rhs, variable.Variable):
-        return MatMulVarVar()(rhs, lhs)
+        return MatMulVarVar()(rhs, self)
     _check_constant_type(rhs)
-    return MatMulConstVar(rhs)(lhs)
+    return MatMulConstVar(rhs)(self)
 
 
 def install_variable_arithmetics():


Test patch: