Fix english doc api: sequence_slice, sigmoid_cross_entropy_with_logits,...

Fix english doc api: sequence_slice, sigmoid_cross_entropy_with_logits, ssd_loss, DetectionMAP, detection_map (#20405)

* Fix english doc api: sequence_slice, sigmoid_cross_entropy_with_logits, ssd_loss, DetectionMAP, detection_map

paddle/fluid/API.spec

@@ -166,7 +166,7 @@ paddle.fluid.layers.reduce_all (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'
 paddle.fluid.layers.reduce_any (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', 'fbc9e73da7a2964ba5693864aed36abb'))
 paddle.fluid.layers.sequence_first_step (ArgSpec(args=['input'], varargs=None, keywords=None, defaults=None), ('document', '227a75392ae194de0504f5c6812dade9'))
 paddle.fluid.layers.sequence_last_step (ArgSpec(args=['input'], varargs=None, keywords=None, defaults=None), ('document', '34372f58331247749e8b0a1663cf233b'))
-paddle.fluid.layers.sequence_slice (ArgSpec(args=['input', 'offset', 'length', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '39fbc5437be389f6c0c769f82fc1fba2'))
+paddle.fluid.layers.sequence_slice (ArgSpec(args=['input', 'offset', 'length', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', 'c051c1b17c1946a1f378bc457bcc63cb'))
 paddle.fluid.layers.dropout (ArgSpec(args=['x', 'dropout_prob', 'is_test', 'seed', 'name', 'dropout_implementation'], varargs=None, keywords=None, defaults=(False, None, None, 'downgrade_in_infer')), ('document', '392dd4bad607fd853f71fec71801044f'))
 paddle.fluid.layers.split (ArgSpec(args=['input', 'num_or_sections', 'dim', 'name'], varargs=None, keywords=None, defaults=(-1, None)), ('document', '64073050d3f172d71ace73d7bbb4168e'))
 paddle.fluid.layers.ctc_greedy_decoder (ArgSpec(args=['input', 'blank', 'input_length', 'padding_value', 'name'], varargs=None, keywords=None, defaults=(None, 0, None)), ('document', '31e0cbec2898efae95853034adadfe2b'))
@@ -271,7 +271,7 @@ paddle.fluid.layers.clip (ArgSpec(args=['x', 'min', 'max', 'name'], varargs=None
 paddle.fluid.layers.clip_by_norm (ArgSpec(args=['x', 'max_norm', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', 'a5f4917fda557ceb834168cdbec6d51b'))
 paddle.fluid.layers.mean (ArgSpec(args=['x', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '597257fb94d0597c404a6a5c91ab5258'))
 paddle.fluid.layers.mul (ArgSpec(args=['x', 'y', 'x_num_col_dims', 'y_num_col_dims', 'name'], varargs=None, keywords=None, defaults=(1, 1, None)), ('document', 'a91eb670033cd103cd8b24624fef5f69'))
-paddle.fluid.layers.sigmoid_cross_entropy_with_logits (ArgSpec(args=['x', 'label', 'ignore_index', 'name', 'normalize'], varargs=None, keywords=None, defaults=(-100, None, False)), ('document', '7637c974f2d749d359acae9062c4d96f'))
+paddle.fluid.layers.sigmoid_cross_entropy_with_logits (ArgSpec(args=['x', 'label', 'ignore_index', 'name', 'normalize'], varargs=None, keywords=None, defaults=(-100, None, False)), ('document', '8cdf9e34f73b6f0ed8b60b59a8207fb6'))
 paddle.fluid.layers.maxout (ArgSpec(args=['x', 'groups', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '406eee439e41988c8a0304186626a0dd'))
 paddle.fluid.layers.space_to_depth (ArgSpec(args=['x', 'blocksize', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '26decdea9376b6b9a0d3432d82ca207b'))
 paddle.fluid.layers.affine_grid (ArgSpec(args=['theta', 'out_shape', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '315b50c1cbd9569375b098c56f1e91c9'))
@@ -412,7 +412,7 @@ paddle.fluid.layers.multi_box_head (ArgSpec(args=['inputs', 'image', 'base_size'
 paddle.fluid.layers.bipartite_match (ArgSpec(args=['dist_matrix', 'match_type', 'dist_threshold', 'name'], varargs=None, keywords=None, defaults=(None, None, None)), ('document', '6f795f407a8e3a3ec3da52726c73405a'))
 paddle.fluid.layers.target_assign (ArgSpec(args=['input', 'matched_indices', 'negative_indices', 'mismatch_value', 'name'], varargs=None, keywords=None, defaults=(None, None, None)), ('document', 'e9685f32d21bec8c013626c0254502c5'))
 paddle.fluid.layers.detection_output (ArgSpec(args=['loc', 'scores', 'prior_box', 'prior_box_var', 'background_label', 'nms_threshold', 'nms_top_k', 'keep_top_k', 'score_threshold', 'nms_eta', 'return_index'], varargs=None, keywords=None, defaults=(0, 0.3, 400, 200, 0.01, 1.0, False)), ('document', '5485bcaceb0cde2695565a2ffd5bbd40'))
-paddle.fluid.layers.ssd_loss (ArgSpec(args=['location', 'confidence', 'gt_box', 'gt_label', 'prior_box', 'prior_box_var', 'background_label', 'overlap_threshold', 'neg_pos_ratio', 'neg_overlap', 'loc_loss_weight', 'conf_loss_weight', 'match_type', 'mining_type', 'normalize', 'sample_size'], varargs=None, keywords=None, defaults=(None, 0, 0.5, 3.0, 0.5, 1.0, 1.0, 'per_prediction', 'max_negative', True, None)), ('document', '14d1eeae0f41b6792be43c1c0be0589b'))
+paddle.fluid.layers.ssd_loss (ArgSpec(args=['location', 'confidence', 'gt_box', 'gt_label', 'prior_box', 'prior_box_var', 'background_label', 'overlap_threshold', 'neg_pos_ratio', 'neg_overlap', 'loc_loss_weight', 'conf_loss_weight', 'match_type', 'mining_type', 'normalize', 'sample_size'], varargs=None, keywords=None, defaults=(None, 0, 0.5, 3.0, 0.5, 1.0, 1.0, 'per_prediction', 'max_negative', True, None)), ('document', '1f1ab4f908ceddef1d99a8363e6826af'))
 paddle.fluid.layers.rpn_target_assign (ArgSpec(args=['bbox_pred', 'cls_logits', 'anchor_box', 'anchor_var', 'gt_boxes', 'is_crowd', 'im_info', 'rpn_batch_size_per_im', 'rpn_straddle_thresh', 'rpn_fg_fraction', 'rpn_positive_overlap', 'rpn_negative_overlap', 'use_random'], varargs=None, keywords=None, defaults=(256, 0.0, 0.5, 0.7, 0.3, True)), ('document', 'd46629656b4ce9b07809e32c0482cbef'))
 paddle.fluid.layers.retinanet_target_assign (ArgSpec(args=['bbox_pred', 'cls_logits', 'anchor_box', 'anchor_var', 'gt_boxes', 'gt_labels', 'is_crowd', 'im_info', 'num_classes', 'positive_overlap', 'negative_overlap'], varargs=None, keywords=None, defaults=(1, 0.5, 0.4)), ('document', '543b2a40641260e745a76b1f7a25fb2a'))
 paddle.fluid.layers.sigmoid_focal_loss (ArgSpec(args=['x', 'label', 'fg_num', 'gamma', 'alpha'], varargs=None, keywords=None, defaults=(2, 0.25)), ('document', '4702891755596c8853aaeb874a5fdb46'))

python/paddle/fluid/layers/detection.py

@@ -1127,14 +1127,14 @@ def detection_map(detect_res,
         overlap_threshold: ${overlap_threshold_comment}
         evaluate_difficult: ${evaluate_difficult_comment}
         has_state: ${has_state_comment}
-        input_states: If not None, It contains 3 elements:
-            1. pos_count ${pos_count_comment}.
-            2. true_pos ${true_pos_comment}.
-            3. false_pos ${false_pos_comment}.
-        out_states: If not None, it contains 3 elements.
-            1. accum_pos_count ${accum_pos_count_comment}.
-            2. accum_true_pos ${accum_true_pos_comment}.
-            3. accum_false_pos ${accum_false_pos_comment}.
+        input_states: (tuple|None) If not None, It contains 3 elements:
+            (1) pos_count ${pos_count_comment}.
+            (2) true_pos ${true_pos_comment}.
+            (3) false_pos ${false_pos_comment}.
+        out_states: (tuple|None) If not None, it contains 3 elements.
+            (1) accum_pos_count ${accum_pos_count_comment}.
+            (2) accum_true_pos ${accum_true_pos_comment}.
+            (3) accum_false_pos ${accum_false_pos_comment}.
         ap_version: ${ap_type_comment}
 
     Returns:
@@ -1146,15 +1146,13 @@ def detection_map(detect_res,
 
             import paddle.fluid as fluid
             from fluid.layers import detection
-            detect_res = fluid.layers.data(
+            detect_res = fluid.data(
                 name='detect_res',
                 shape=[10, 6],
-                append_batch_size=False,
                 dtype='float32')
-            label = fluid.layers.data(
+            label = fluid.data(
                 name='label',
                 shape=[10, 6],
-                append_batch_size=False,
                 dtype='float32')
 
             map_out = detection.detection_map(detect_res, label, 21)
@@ -1446,22 +1444,28 @@ def ssd_loss(location,
         location (Variable): The location predictions are a 3D Tensor with
             shape [N, Np, 4], N is the batch size, Np is total number of
             predictions for each instance. 4 is the number of coordinate values,
-            the layout is [xmin, ymin, xmax, ymax].
+            the layout is [xmin, ymin, xmax, ymax].The data type is float32 or
+            float64.
         confidence (Variable): The confidence predictions are a 3D Tensor
             with shape [N, Np, C], N and Np are the same as they are in
-            `location`, C is the class number.
+            `location`, C is the class number.The data type is float32 or
+            float64.
         gt_box (Variable): The ground-truth bounding boxes (bboxes) are a 2D
             LoDTensor with shape [Ng, 4], Ng is the total number of ground-truth
-            bboxes of mini-batch input.
+            bboxes of mini-batch input.The data type is float32 or float64.
         gt_label (Variable): The ground-truth labels are a 2D LoDTensor
-            with shape [Ng, 1].
+            with shape [Ng, 1].Ng is the total number of ground-truth bboxes of
+            mini-batch input, 1 is the number of class. The data type is float32
+            or float64.
         prior_box (Variable): The prior boxes are a 2D Tensor with shape [Np, 4].
+            Np and 4 are the same as they are in `location`. The data type is
+            float32 or float64.
         prior_box_var (Variable): The variance of prior boxes are a 2D Tensor
-            with shape [Np, 4].
+            with shape [Np, 4]. Np and 4 are the same as they are in `prior_box`
         background_label (int): The index of background label, 0 by default.
         overlap_threshold (float): If match_type is 'per_prediction', use
-            `overlap_threshold` to determine the extra matching bboxes when
-             finding matched boxes. 0.5 by default.
+            'overlap_threshold' to determine the extra matching bboxes when finding \
+            matched boxes. 0.5 by default.
         neg_pos_ratio (float): The ratio of the negative boxes to the positive
             boxes, used only when mining_type is 'max_negative', 3.0 by default.
         neg_overlap (float): The negative overlap upper bound for the unmatched
@@ -1479,32 +1483,34 @@ def ssd_loss(location,
             mining_type is 'hard_example'.
 
     Returns:
-        The weighted sum of the localization loss and confidence loss, with \
-        shape [N * Np, 1], N and Np are the same as they are in `location`.
+        Variable(Tensor):  The weighted sum of the localization loss and confidence loss, \
+        with shape [N * Np, 1], N and Np are the same as they are in
+        `location`.The data type is float32 or float64.
 
     Raises:
         ValueError: If mining_type is 'hard_example', now only support mining \
         type of `max_negative`.
 
     Examples:
-        >>> import paddle.fluid as fluid
-        >>> pb = fluid.layers.data(
-        >>>                   name='prior_box',
-        >>>                   shape=[10, 4],
-        >>>                   append_batch_size=False,
-        >>>                   dtype='float32')
-        >>> pbv = fluid.layers.data(
-        >>>                   name='prior_box_var',
-        >>>                   shape=[10, 4],
-        >>>                   append_batch_size=False,
-        >>>                   dtype='float32')
-        >>> loc = fluid.layers.data(name='target_box', shape=[10, 4], dtype='float32')
-        >>> scores = fluid.layers.data(name='scores', shape=[10, 21], dtype='float32')
-        >>> gt_box = fluid.layers.data(
-        >>>         name='gt_box', shape=[4], lod_level=1, dtype='float32')
-        >>> gt_label = fluid.layers.data(
-        >>>         name='gt_label', shape=[1], lod_level=1, dtype='float32')
-        >>> loss = fluid.layers.ssd_loss(loc, scores, gt_box, gt_label, pb, pbv)
+
+        .. code-block:: python
+
+            import paddle.fluid as fluid
+            pb = fluid.data(
+                           name='prior_box',
+                           shape=[10, 4],
+                           dtype='float32')
+            pbv = fluid.data(
+                           name='prior_box_var',
+                           shape=[10, 4],
+                           dtype='float32')
+            loc = fluid.data(name='target_box', shape=[10, 4], dtype='float32')
+            scores = fluid.data(name='scores', shape=[10, 21], dtype='float32')
+            gt_box = fluid.data(
+                 name='gt_box', shape=[4], lod_level=1, dtype='float32')
+            gt_label = fluid.data(
+                 name='gt_label', shape=[1], lod_level=1, dtype='float32')
+            loss = fluid.layers.ssd_loss(loc, scores, gt_box, gt_label, pb, pbv)
     """
 
     helper = LayerHelper('ssd_loss', **locals())

python/paddle/fluid/layers/nn.py

@@ -3220,12 +3220,15 @@ def sequence_slice(input, offset, length, name=None):
           should be equal. The **offset** should start from 0.
 
     Args:
-        input(Variable): The input Variable which consists of the complete
-                         sequences.
-        offset(Variable): The offset to slice each sequence.
-        length(Variable): The length of each subsequence.
-        name(str|None): A name for this layer(optional). If set None, the
-                        layer will be named automatically.
+        input(Variable): LoDTensor, The input Variable which consists of the complete
+                         sequences.The data type is float32 or float64.
+        offset(Variable): LoDTensor, The offset to slice each sequence.The data
+                         type is int32 or int64.
+        length(Variable): LoDTensor, The length of each subsequence.The data
+                         type is int32 or int64.
+        name(str|None): The default value is None.  Normally there is no need
+                        for user to set this property.  For more information,
+                        please refer to :ref:`api_guide_Name`
 
     Returns:
         Variable: The output subsequences.
@@ -3236,7 +3239,7 @@ def sequence_slice(input, offset, length, name=None):
 
              import paddle.fluid as fluid
              import numpy as np
-             seqs = fluid.layers.data(name='x', shape=[10, 5],
+             seqs = fluid.data(name='x', shape=[10, 5],
                               dtype='float32', lod_level=1)
              offset = fluid.layers.assign(input=np.array([[0, 1]]).astype("int32"))
              length = fluid.layers.assign(input=np.array([[2, 1]]).astype("int32"))
@@ -13935,8 +13938,10 @@ def sigmoid_cross_entropy_with_logits(x,
     Args:
         x(${x_type}): ${x_comment}
         label(${label_type}): ${label_comment}
-        ignore_index(&{ignore_index}): ${ignore_index_comment}
-        name(basestring|None): Name of the output.
+        ignore_index(int): ${ignore_index_comment}
+        name(str|None): The default value is None.  Normally there is
+            no need for user to set this property.  For more information,
+            please refer to :ref:`api_guide_Name`
         normalize(bool): If true, divide the output by the number of
             targets != ignore_index.
 
@@ -13947,9 +13952,9 @@ def sigmoid_cross_entropy_with_logits(x,
         .. code-block:: python
 
             import paddle.fluid as fluid
-            input = fluid.layers.data(
+            input = fluid.data(
                 name='data', shape=[10], dtype='float32')
-            label = fluid.layers.data(
+            label = fluid.data(
                 name='data', shape=[10], dtype='float32')
             loss = fluid.layers.sigmoid_cross_entropy_with_logits(
                 x=input,

python/paddle/fluid/metrics.py

@@ -701,6 +701,8 @@ class DetectionMAP(object):
     1. calculate the true positive and false positive according to the input
        of detection and labels.
     2. calculate mAP value, support two versions: '11 point' and 'integral'.
+       11point: the 11-point interpolated average precision.
+       integral: the natural integral of the precision-recall curve.
 
     Please get more information from the following articles:
 
@@ -709,15 +711,18 @@ class DetectionMAP(object):
       https://arxiv.org/abs/1512.02325
 
     Args:
-        input (Variable): The detection results, which is a LoDTensor with shape
+        input (Variable): LoDTensor, The detection results, which is a LoDTensor with shape
             [M, 6]. The layout is [label, confidence, xmin, ymin, xmax, ymax].
-        gt_label (Variable): The ground truth label index, which is a LoDTensor
-            with shape [N, 1].
-        gt_box (Variable): The ground truth bounding box (bbox), which is a
+            The data type is float32 or float64.
+        gt_label (Variable): LoDTensor, The ground truth label index, which is a LoDTensor
+            with shape [N, 1].The data type is float32 or float64.
+        gt_box (Variable): LoDTensor, The ground truth bounding box (bbox), which is a
             LoDTensor with shape [N, 4]. The layout is [xmin, ymin, xmax, ymax].
-        gt_difficult (Variable|None): Whether this ground truth is a difficult
+            The data type is float32 or float64.
+        gt_difficult (Variable|None): LoDTensor, Whether this ground truth is a difficult
             bounding bbox, which can be a LoDTensor [N, 1] or not set. If None,
-            it means all the ground truth labels are not difficult bbox.
+            it means all the ground truth labels are not difficult bbox.The
+            data type is int.
         class_num (int): The class number.
         background_label (int): The index of background label, the background
             label will be ignored. If set to -1, then all categories will be
@@ -727,40 +732,37 @@ class DetectionMAP(object):
         evaluate_difficult (bool): Whether to consider difficult ground truth
             for evaluation, True by default. This argument does not work when
             gt_difficult is None.
-        ap_version (string): The average precision calculation ways, it must be
+        ap_version (str): The average precision calculation ways, it must be
             'integral' or '11point'. Please check
             https://sanchom.wordpress.com/tag/average-precision/ for details.
-            - 11point: the 11-point interpolated average precision.
-            - integral: the natural integral of the precision-recall curve.
 
     Examples:
         .. code-block:: python
 
             import paddle.fluid as fluid
-            import paddle.fluid.layers as layers
 
-            batch_size = -1 # can be any size
+            batch_size = None # can be any size
             image_boxs_num = 10
             bounding_bboxes_num = 21
 
-            pb = layers.data(name='prior_box', shape=[image_boxs_num, 4],
-                append_batch_size=False, dtype='float32')
+            pb = fluid.data(name='prior_box', shape=[image_boxs_num, 4],
+                       dtype='float32')
 
-            pbv = layers.data(name='prior_box_var', shape=[image_boxs_num, 4],
-                append_batch_size=False, dtype='float32')
+            pbv = fluid.data(name='prior_box_var', shape=[image_boxs_num, 4],
+                         dtype='float32')
 
-            loc = layers.data(name='target_box', shape=[batch_size, bounding_bboxes_num, 4],
-                append_batch_size=False, dtype='float32')
+            loc = fluid.data(name='target_box', shape=[batch_size, bounding_bboxes_num, 4],
+                        dtype='float32')
 
-            scores = layers.data(name='scores', shape=[batch_size, bounding_bboxes_num, image_boxs_num],
-                append_batch_size=False, dtype='float32')
+            scores = fluid.data(name='scores', shape=[batch_size, bounding_bboxes_num, image_boxs_num],
+                            dtype='float32')
 
             nmsed_outs = fluid.layers.detection_output(scores=scores,
                 loc=loc, prior_box=pb, prior_box_var=pbv)
 
-            gt_box = fluid.layers.data(name="gt_box", shape=[batch_size, 4], dtype="float32")
-            gt_label = fluid.layers.data(name="gt_label", shape=[batch_size, 1], dtype="float32")
-            difficult = fluid.layers.data(name="difficult", shape=[batch_size, 1], dtype="float32")
+            gt_box = fluid.data(name="gt_box", shape=[batch_size, 4], dtype="float32")
+            gt_label = fluid.data(name="gt_label", shape=[batch_size, 1], dtype="float32")
+            difficult = fluid.data(name="difficult", shape=[batch_size, 1], dtype="float32")
 
             exe = fluid.Executor(fluid.CUDAPlace(0))
             map_evaluator = fluid.metrics.DetectionMAP(nmsed_outs, gt_label, gt_box, difficult, class_num = 3)