[Docs] Fix the format of return (#1462)

* [Docs] Fix the format of return

* replace List with list

* format the documentation of optimizer

* Update ops docstring (#2

)

* update ops docstring

* fix typos
Co-authored-by: ChaimZhu <zhuchenming@pjlab.org.cn>
Co-authored-by: ChaimZhu <zhuchenming@pjlab.org.cn>

mmcv/ops/points_in_boxes.py

@@ -12,13 +12,14 @@ def points_in_boxes_part(points, boxes):
     """Find the box in which each point is (CUDA).
 
     Args:
-        points (torch.Tensor): [B, M, 3], [x, y, z] in LiDAR/DEPTH coordinate
+        points (torch.Tensor): [B, M, 3], [x, y, z] in LiDAR/DEPTH coordinate.
         boxes (torch.Tensor): [B, T, 7],
             num_valid_boxes <= T, [x, y, z, x_size, y_size, z_size, rz] in
-            LiDAR/DEPTH coordinate, (x, y, z) is the bottom center
+            LiDAR/DEPTH coordinate, (x, y, z) is the bottom center.
 
     Returns:
-        box_idxs_of_pts (torch.Tensor): (B, M), default background = -1
+        torch.Tensor: Return the box indices of points with the shape of
+        (B, M). Default background = -1.
     """
     assert points.shape[0] == boxes.shape[0], \
         'Points and boxes should have the same batch size, ' \
@@ -67,7 +68,8 @@ def points_in_boxes_cpu(points, boxes):
             (x, y, z) is the bottom center.
 
     Returns:
-        box_idxs_of_pts (torch.Tensor): (B, M, T), default background = 0.
+        torch.Tensor: Return the box indices of points with the shape of
+        (B, M, T). Default background = 0.
     """
     assert points.shape[0] == boxes.shape[0], \
         'Points and boxes should have the same batch size, ' \
@@ -102,7 +104,8 @@ def points_in_boxes_all(points, boxes):
             (x, y, z) is the bottom center.
 
     Returns:
-        box_idxs_of_pts (torch.Tensor): (B, M, T), default background = 0.
+        torch.Tensor: Return the box indices of points with the shape of
+        (B, M, T). Default background = 0.
     """
     assert boxes.shape[0] == points.shape[0], \
         'Points and boxes should have the same batch size, ' \

mmcv/ops/points_sampler.py

@@ -12,13 +12,13 @@ def calc_square_dist(point_feat_a, point_feat_b, norm=True):
     """Calculating square distance between a and b.
 
     Args:
-        point_feat_a (Tensor): (B, N, C) Feature vector of each point.
-        point_feat_b (Tensor): (B, M, C) Feature vector of each point.
-        norm (Bool, optional): Whether to normalize the distance.
+        point_feat_a (torch.Tensor): (B, N, C) Feature vector of each point.
+        point_feat_b (torch.Tensor): (B, M, C) Feature vector of each point.
+        norm (bool, optional): Whether to normalize the distance.
             Default: True.
 
     Returns:
-        Tensor: (B, N, M) Distance between each pair points.
+        torch.Tensor: (B, N, M) Square distance between each point pair.
     """
     num_channel = point_feat_a.shape[-1]
     # [bs, n, 1]
@@ -92,11 +92,12 @@ class PointsSampler(nn.Module):
     def forward(self, points_xyz, features):
         """
         Args:
-            points_xyz (Tensor): (B, N, 3) xyz coordinates of the features.
-            features (Tensor): (B, C, N) Descriptors of the features.
+            points_xyz (torch.Tensor): (B, N, 3) xyz coordinates of
+                the points.
+            features (torch.Tensor): (B, C, N) features of the points.
 
         Returns:
-            Tensor: (B, npoint, sample_num) Indices of sampled points.
+            torch.Tensor: (B, npoint, sample_num) Indices of sampled points.
         """
         indices = []
         last_fps_end_index = 0

mmcv/ops/roiaware_pool3d.py

@@ -43,7 +43,8 @@ class RoIAwarePool3d(nn.Module):
             pts_feature (torch.Tensor): [npoints, C], features of input points.
 
         Returns:
-            pooled_features (torch.Tensor): [N, out_x, out_y, out_z, C]
+            torch.Tensor: Pooled features whose shape is
+            [N, out_x, out_y, out_z, C].
         """
 
         return RoIAwarePool3dFunction.apply(rois, pts, pts_feature,
@@ -70,8 +71,8 @@ class RoIAwarePool3dFunction(Function):
                 pool).
 
         Returns:
-            pooled_features (torch.Tensor): [N, out_x, out_y, out_z, C], output
-                pooled features.
+            torch.Tensor: Pooled features whose shape is
+            [N, out_x, out_y, out_z, C].
         """
 
         if isinstance(out_size, int):

mmcv/ops/roipoint_pool3d.py

@@ -30,9 +30,9 @@ class RoIPointPool3d(nn.Module):
             boxes3d (B, M, 7), Input bounding boxes whose shape is (B, M, 7).
 
         Returns:
-            pooled_features (torch.Tensor): The output pooled features whose
-                shape is (B, M, 512, 3 + C).
-            pooled_empty_flag (torch.Tensor): Empty flag whose shape is (B, M).
+            tuple[torch.Tensor]: A tuple contains two elements. The first one
+            is the pooled features whose shape is (B, M, 512, 3 + C). The
+            second is an empty flag whose shape is (B, M).
         """
         return RoIPointPool3dFunction.apply(points, point_features, boxes3d,
                                             self.num_sampled_points)
@@ -52,9 +52,9 @@ class RoIPointPool3dFunction(Function):
                 Default: 512.
 
         Returns:
-            pooled_features (torch.Tensor): The output pooled features whose
-                shape is (B, M, 512, 3 + C).
-            pooled_empty_flag (torch.Tensor): Empty flag whose shape is (B, M).
+            tuple[torch.Tensor]: A tuple contains two elements. The first one
+            is the pooled features whose shape is (B, M, 512, 3 + C). The
+            second is an empty flag whose shape is (B, M).
         """
         assert len(points.shape) == 3 and points.shape[2] == 3
         batch_size, boxes_num, feature_len = points.shape[0], boxes3d.shape[

mmcv/ops/saconv.py

@@ -12,8 +12,9 @@ from mmcv.utils import TORCH_VERSION, digit_version
 class SAConv2d(ConvAWS2d):
     """SAC (Switchable Atrous Convolution)
 
-    This is an implementation of SAC in DetectoRS
-    (https://arxiv.org/pdf/2006.02334.pdf).
+    This is an implementation of `DetectoRS: Detecting Objects with Recursive
+    Feature Pyramid and Switchable Atrous Convolution
+    <https://arxiv.org/abs/2006.02334>`_.
 
     Args:
         in_channels (int): Number of channels in the input image

mmcv/ops/scatter_points.py

@@ -25,10 +25,11 @@ class _DynamicScatter(Function):
                 'mean'. Default: 'max'.
 
         Returns:
-            voxel_feats (torch.Tensor): [M, C]. Reduced features, input
-                features that shares the same voxel coordinates are reduced to
-                one row.
-            voxel_coors (torch.Tensor): [M, ndim]. Voxel coordinates.
+            tuple[torch.Tensor]: tuple[torch.Tensor]: A tuple contains two
+            elements. The first one is the voxel features with shape [M, C]
+            which are respectively reduced from input features that share
+            the same voxel coordinates . The second is voxel coordinates
+            with shape [M, ndim].
         """
         results = ext_module.dynamic_point_to_voxel_forward(
             feats, coors, reduce_type)
@@ -88,9 +89,11 @@ class DynamicScatter(nn.Module):
                 multi-dim voxel index) of each points.
 
         Returns:
-            voxel_feats (torch.Tensor): Reduced features, input features that
-                shares the same voxel coordinates are reduced to one row.
-            voxel_coors (torch.Tensor): Voxel coordinates.
+            tuple[torch.Tensor]: tuple[torch.Tensor]: A tuple contains two
+            elements. The first one is the voxel features with shape [M, C]
+            which are respectively reduced from input features that share
+            the same voxel coordinates . The second is voxel coordinates
+            with shape [M, ndim].
         """
         reduce = 'mean' if self.average_points else 'max'
         return dynamic_scatter(points.contiguous(), coors.contiguous(), reduce)
@@ -104,9 +107,11 @@ class DynamicScatter(nn.Module):
                 multi-dim voxel index) of each points.
 
         Returns:
-            voxel_feats (torch.Tensor): Reduced features, input features that
-                shares the same voxel coordinates are reduced to one row.
-            voxel_coors (torch.Tensor): Voxel coordinates.
+            tuple[torch.Tensor]:tuple[torch.Tensor]: A tuple contains two
+            elements. The first one is the voxel features with shape [M, C]
+            which are respectively reduced from input features that share
+            the same voxel coordinates . The second is voxel coordinates
+            with shape [M, ndim].
         """
         if coors.size(-1) == 3:
             return self.forward_single(points, coors)

mmcv/ops/three_interpolate.py

@@ -21,14 +21,15 @@ class ThreeInterpolate(Function):
                 weight: torch.Tensor) -> torch.Tensor:
         """
         Args:
-            features (Tensor): (B, C, M) Features descriptors to be
-                interpolated
-            indices (Tensor): (B, n, 3) index three nearest neighbors
-                of the target features in features
-            weight (Tensor): (B, n, 3) weights of interpolation
+            features (torch.Tensor): (B, C, M) Features descriptors to be
+                interpolated.
+            indices (torch.Tensor): (B, n, 3) indices of three nearest
+                neighbor features for the target features.
+            weight (torch.Tensor): (B, n, 3) weights of three nearest
+                neighbor features for the target features.
 
         Returns:
-            Tensor: (B, C, N) tensor of the interpolated features
+            torch.Tensor: (B, C, N) tensor of the interpolated features
         """
         assert features.is_contiguous()
         assert indices.is_contiguous()
@@ -49,10 +50,10 @@ class ThreeInterpolate(Function):
     ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
         """
         Args:
-            grad_out (Tensor): (B, C, N) tensor with gradients of outputs
+            grad_out (torch.Tensor): (B, C, N) tensor with gradients of outputs
 
         Returns:
-            Tensor: (B, C, M) tensor with gradients of features
+            torch.Tensor: (B, C, M) tensor with gradients of features
         """
         idx, weight, m = ctx.three_interpolate_for_backward
         B, c, n = grad_out.size()

mmcv/ops/three_nn.py

@@ -20,14 +20,14 @@ class ThreeNN(Function):
                 source: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
         """
         Args:
-            target (Tensor): shape (B, N, 3), points set that needs to
+            target (torch.Tensor): shape (B, N, 3), points set that needs to
                 find the nearest neighbors.
-            source (Tensor): shape (B, M, 3), points set that is used
+            source (torch.Tensor): shape (B, M, 3), points set that is used
                 to find the nearest neighbors of points in target set.
 
         Returns:
-            Tensor: shape (B, N, 3), L2 distance of each point in target
-                set to their corresponding nearest neighbors.
+            torch.Tensor: shape (B, N, 3), L2 distance of each point in target
+            set to their corresponding top three nearest neighbors.
         """
         target = target.contiguous()
         source = source.contiguous()

mmcv/ops/tin_shift.py

@@ -51,7 +51,9 @@ class TINShift(nn.Module):
     Temporal Interlace shift is a differentiable temporal-wise frame shifting
     which is proposed in "Temporal Interlacing Network"
 
-    Please refer to https://arxiv.org/abs/2001.06499 for more details.
+    Please refer to `Temporal Interlacing Network
+    <https://arxiv.org/abs/2001.06499>`_ for more details.
+
     Code is modified from https://github.com/mit-han-lab/temporal-shift-module
     """
 
@@ -59,8 +61,9 @@ class TINShift(nn.Module):
         """Perform temporal interlace shift.
 
         Args:
-            input (Tensor): Feature map with shape [N, num_segments, C, H * W].
-            shift (Tensor): Shift tensor with shape [N, num_segments].
+            input (torch.Tensor): Feature map with shape
+                [N, num_segments, C, H * W].
+            shift (torch.Tensor): Shift tensor with shape [N, num_segments].
 
         Returns:
             Feature map after temporal interlace shift.

mmcv/ops/upfirdn2d.py

@@ -248,8 +248,8 @@ def upfirdn2d(input, kernel, up=1, down=1, pad=(0, 0)):
     https://www.mathworks.com/help/signal/ref/upfirdn.html
 
     Args:
-        input (Tensor): Tensor with shape of (n, c, h, w).
-        kernel (Tensor): Filter kernel.
+        input (torch.Tensor): Tensor with shape of (n, c, h, w).
+        kernel (torch.Tensor): Filter kernel.
         up (int | tuple[int], optional): Upsampling factor. If given a number,
             we will use this factor for the both height and width side.
             Defaults to 1.
@@ -260,7 +260,7 @@ def upfirdn2d(input, kernel, up=1, down=1, pad=(0, 0)):
             (x_pad_0, x_pad_1, y_pad_0, y_pad_1). Defaults to (0, 0).
 
     Returns:
-        Tensor: Tensor after UpFIRDn.
+        torch.Tensor: Tensor after UpFIRDn.
     """
     if input.device.type == 'cpu':
         if len(pad) == 2:

mmcv/ops/voxelize.py

@@ -36,13 +36,12 @@ class _Voxelization(Function):
                 Default: 20000.
 
         Returns:
-            voxels_out (torch.Tensor): Output voxels with the shape of [M,
-                max_points, ndim]. Only contain points and returned when
-                max_points != -1.
-            coors_out (torch.Tensor): Output coordinates with the shape of
-                [M, 3].
-            num_points_per_voxel_out (torch.Tensor): Num points per voxel with
-                the shape of [M]. Only returned when max_points != -1.
+            tuple[torch.Tensor]: tuple[torch.Tensor]: A tuple contains three
+            elements. The first one is the output voxels with the shape of
+            [M, max_points, n_dim], which only contain points and returned
+            when max_points != -1. The second is the voxel coordinates with
+            shape of [M, 3]. The last is number of point per voxel with the
+            shape of [M], which only returned when max_points != -1.
         """
         if max_points == -1 or max_voxels == -1:
             coors = points.new_zeros(size=(points.size(0), 3), dtype=torch.int)
@@ -84,8 +83,8 @@ voxelization = _Voxelization.apply
 class Voxelization(nn.Module):
     """Convert kitti points(N, >=3) to voxels.
 
-    Please refer to `PVCNN <https://arxiv.org/abs/1907.03739>`_ for more
-    details.
+    Please refer to `Point-Voxel CNN for Efficient 3D Deep Learning
+    <https://arxiv.org/abs/1907.03739>`_ for more details.
 
     Args:
         voxel_size (tuple or float): The size of voxel with the shape of [3].

mmcv/runner/optimizer/default_constructor.py

@@ -46,16 +46,17 @@ class DefaultOptimizerConstructor:
       would not be added into optimizer. Default: False.
 
     Note:
+
         1. If the option ``dcn_offset_lr_mult`` is used, the constructor will
-            override the effect of ``bias_lr_mult`` in the bias of offset
-            layer. So be careful when using both ``bias_lr_mult`` and
-            ``dcn_offset_lr_mult``. If you wish to apply both of them to the
-            offset layer in deformable convs, set ``dcn_offset_lr_mult``
-            to the original ``dcn_offset_lr_mult`` * ``bias_lr_mult``.
+        override the effect of ``bias_lr_mult`` in the bias of offset layer.
+        So be careful when using both ``bias_lr_mult`` and
+        ``dcn_offset_lr_mult``. If you wish to apply both of them to the offset
+        layer in deformable convs, set ``dcn_offset_lr_mult`` to the original
+        ``dcn_offset_lr_mult`` * ``bias_lr_mult``.
+
         2. If the option ``dcn_offset_lr_mult`` is used, the constructor will
-            apply it to all the DCN layers in the model. So be careful when
-            the model contains multiple DCN layers in places other than
-            backbone.
+        apply it to all the DCN layers in the model. So be careful when the
+        model contains multiple DCN layers in places other than backbone.
 
     Args:
         model (:obj:`nn.Module`): The model with parameters to be optimized.