From 32959e031eccd5a0f9ba15fe86de1115cc80d4cd Mon Sep 17 00:00:00 2001
From: Huihuang Zheng <zhhsplendid@gmail.com>
Date: Mon, 2 Dec 2019 15:54:39 +0800
Subject: [PATCH] Add English Document for cond API (#21452)

Add English doc for cond
---
 python/paddle/fluid/layers/control_flow.py | 74 +++++++++++++++++++++-
 1 file changed, 73 insertions(+), 1 deletion(-)

diff --git a/python/paddle/fluid/layers/control_flow.py b/python/paddle/fluid/layers/control_flow.py
index 45933463f6..4241d57064 100755
--- a/python/paddle/fluid/layers/control_flow.py
+++ b/python/paddle/fluid/layers/control_flow.py
@@ -1749,7 +1749,79 @@ def copy_var_to_parent_block(var, layer_helper):
 
 def cond(pred, true_fn=None, false_fn=None, name=None):
     """
-    TODO:(huihuangzheng) developing
+    This API returns ``true_fn()`` if the predicate ``pred`` is true else
+    ``false_fn()`` . Users could also set ``true_fn`` or ``false_fn`` to
+    ``None`` if do nothing and this API will treat the callable simply returns
+    ``None`` in this case.
+
+    ``true_fn`` and ``false_fn`` should return same nest structure of tensors
+    or both return ``None`` if user doens't like to return anything. A nest
+    structure of tensors in PaddlePaddle is tensor(s), or tuple of tensors, or
+    list of tensors.
+    
+    Note: 
+        The tuples or lists in ``true_fn`` and ``false_fn`` must have same
+        shape because of dataflow model of PaddlePaddle while the tensors in the
+        tuples or the lists can have different shapes.
+
+    Args:
+        pred(Variable): A boolean tensor whose numel should be 1. The boolean
+            value determines whether to return the result of ``true_fn`` or
+            ``false_fn``
+        true_fn(callable): A callable to be performed if ``pred`` is true
+        false_fn(callable): A callable to be performed if ``pred`` is false
+        name(str, optional): The default value is ``None``. Normally users
+             don't have to set this parameter. For more information, please
+             refer to :ref:`api_guide_Name`.
+
+    Raises:
+        TypeError: if ``true_fn`` or ``false_fn`` is not callable.
+        ValueError: if ``true_fn`` and ``false_fn`` doesn't return the same
+            nest structure of tensors.
+
+    Examples:
+        .. code-block:: python
+
+            import paddle.fluid as fluid
+            import paddle.fluid.layers as layers
+            from paddle.fluid.executor import Executor
+            from paddle.fluid.framework import Program, program_guard
+
+            #
+            # pseudocode:
+            # if 0.1 < 0.23:
+            #     return 1, True
+            # else:
+            #     return 3, 2
+            #
+
+            def true_func():
+                return layers.fill_constant(
+                    shape=[1, 2], dtype='int32', value=1), layers.fill_constant(
+                        shape=[2, 3], dtype='bool', value=True)
+
+            def false_func():
+                return layers.fill_constant(
+                    shape=[3, 4], dtype='float32', value=3), layers.fill_constant(
+                        shape=[4, 5], dtype='int64', value=2)
+
+            main_program = Program()
+            startup_program = Program()
+            with program_guard(main_program, startup_program):
+                x = layers.fill_constant(shape=[1], dtype='float32', value=0.1)
+                y = layers.fill_constant(shape=[1], dtype='float32', value=0.23)
+                pred = layers.less_than(x, y)            
+                out = layers.cond(pred, true_func, false_func)
+                # out is a tuple containing 2 tensors
+
+            place = fluid.CUDAPlace(0) if fluid.core.is_compiled_with_cuda(
+            ) else fluid.CPUPlace()
+            exe = fluid.Executor(place)
+            ret = exe.run(main_program, fetch_list=out)
+            # ret[0] = [[1 1]]
+            # ret[1] = [[ True  True  True]
+            #           [ True  True  True]]
+
     """
     helper = LayerHelper('cond', **locals())
     true_output = None
-- 
GitLab