[Docs] Fix the format of return (open-mmlab#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 <[email protected]>

Co-authored-by: ChaimZhu <[email protected]>

mmcv/fileio/file_client.py

@@ -246,7 +246,7 @@ def isdir(self, filepath: Union[str, Path]) -> bool:
 
         Returns:
             bool: Return ``True`` if ``filepath`` points to a directory,
-                ``False`` otherwise.
+            ``False`` otherwise.
         """
         if not has_method(self._client, 'isdir'):
             raise NotImplementedError(
@@ -266,7 +266,7 @@ def isfile(self, filepath: Union[str, Path]) -> bool:
 
         Returns:
             bool: Return ``True`` if ``filepath`` points to a file, ``False``
-                otherwise.
+            otherwise.
         """
         if not has_method(self._client, 'contains'):
             raise NotImplementedError(
@@ -598,7 +598,7 @@ def isdir(self, filepath: Union[str, Path]) -> bool:
 
         Returns:
             bool: Return ``True`` if ``filepath`` points to a directory,
-                ``False`` otherwise.
+            ``False`` otherwise.
         """
         return osp.isdir(filepath)
 
@@ -610,7 +610,7 @@ def isfile(self, filepath: Union[str, Path]) -> bool:
 
         Returns:
             bool: Return ``True`` if ``filepath`` points to a file, ``False``
-                otherwise.
+            otherwise.
         """
         return osp.isfile(filepath)
 
@@ -839,8 +839,8 @@ def parse_uri_prefix(uri: Union[str, Path]) -> Optional[str]:
             's3'
 
         Returns:
-            str | None: Return the prefix of uri if the uri contains '://'
-                else ``None``.
+            str | None: Return the prefix of uri if the uri contains '://' else
+            ``None``.
         """
         assert is_filepath(uri)
         uri = str(uri)
@@ -987,7 +987,7 @@ def get(self, filepath: Union[str, Path]) -> Union[bytes, memoryview]:
 
         Returns:
             bytes | memoryview: Expected bytes object or a memory view of the
-                bytes object.
+            bytes object.
         """
         return self.client.get(filepath)
 
@@ -1060,7 +1060,7 @@ def isdir(self, filepath: Union[str, Path]) -> bool:
 
         Returns:
             bool: Return ``True`` if ``filepath`` points to a directory,
-                ``False`` otherwise.
+            ``False`` otherwise.
         """
         return self.client.isdir(filepath)
 

mmcv/ops/assign_score_withk.py

@@ -84,9 +84,12 @@ def backward(ctx, grad_out):
             grad_out (torch.Tensor): (B, out_dim, npoint, K)
 
         Returns:
-            grad_scores (torch.Tensor): (B, npoint, K, M)
-            grad_point_features (torch.Tensor): (B, N, M, out_dim)
-            grad_center_features (torch.Tensor): (B, N, M, out_dim)
+            tuple[torch.Tensor]: A tuple contains five elements. The first one
+            is the gradient of ``scores`` whose shape is (B, npoint, K, M). The
+            second is the gradient of ``point_features`` whose shape is
+            (B, N, M, out_dim). The third is the gradient of
+            ``center_features`` with the shape of (B, N, M, out_dim). The last
+            two are ``None``.
         """
         _, point_features, center_features, scores, knn_idx = ctx.saved_tensors
 

mmcv/ops/ball_query.py

@@ -19,11 +19,12 @@ def forward(ctx, min_radius: float, max_radius: float, sample_num: int,
             max_radius (float): maximum radius of the balls.
             sample_num (int): maximum number of features in the balls.
             xyz (Tensor): (B, N, 3) xyz coordinates of the features.
-            center_xyz (Tensor): (B, npoint, 3) centers of the ball query.
+            center_xyz (torch.Tensor): (B, npoint, 3) centers of the ball
+                query.
 
         Returns:
-            Tensor: (B, npoint, nsample) tensor with the indices of
-                the features that form the query balls.
+            torch.Tensor: (B, npoint, nsample) tensor with the indices of the
+            features that form the query balls.
         """
         assert center_xyz.is_contiguous()
         assert xyz.is_contiguous()

mmcv/ops/bbox.py

@@ -12,14 +12,16 @@ def bbox_overlaps(bboxes1, bboxes2, mode='iou', aligned=False, offset=0):
     bboxes1 and bboxes2.
 
     Args:
-        bboxes1 (Tensor): shape (m, 4) in <x1, y1, x2, y2> format or empty.
-        bboxes2 (Tensor): shape (n, 4) in <x1, y1, x2, y2> format or empty.
-            If aligned is ``True``, then m and n must be equal.
+        bboxes1 (torch.Tensor): shape (m, 4) in <x1, y1, x2, y2> format or
+            empty.
+        bboxes2 (torch.Tensor): shape (n, 4) in <x1, y1, x2, y2> format or
+            empty. If aligned is ``True``, then m and n must be equal.
         mode (str): "iou" (intersection over union) or iof (intersection over
             foreground).
 
     Returns:
-        ious(Tensor): shape (m, n) if aligned == False else shape (m, 1)
+        torch.Tensor: Return the ious betweens boxes. If ``aligned`` is
+        ``False``, the shape of ious is (m, n) else (m, 1).
 
     Example:
         >>> bboxes1 = torch.FloatTensor([

mmcv/ops/border_align.py

@@ -72,17 +72,17 @@ class BorderAlign(nn.Module):
 
     For each border line (e.g. top, left, bottom or right) of each box,
     border_align does the following:
-        1. uniformly samples `pool_size`+1 positions on this line, involving \
-           the start and end points.
-        2. the corresponding features on these points are computed by \
-           bilinear interpolation.
-        3. max pooling over all the `pool_size`+1 positions are used for \
-           computing pooled feature.
+
+    1. uniformly samples ``pool_size`` +1 positions on this line, involving
+       the start and end points.
+    2. the corresponding features on these points are computed by bilinear
+       interpolation.
+    3. max pooling over all the ``pool_size`` +1 positions are used for
+       computing pooled feature.
 
     Args:
         pool_size (int): number of positions sampled over the boxes' borders
             (e.g. top, bottom, left, right).
-
     """
 
     def __init__(self, pool_size):
@@ -98,8 +98,8 @@ def forward(self, input, boxes):
             boxes: Boxes with shape [N,H*W,4]. Coordinate format (x1,y1,x2,y2).
 
         Returns:
-            Tensor: Pooled features with shape [N,C,H*W,4]. The order is
-                (top,left,bottom,right) for the last dimension.
+            torch.Tensor: Pooled features with shape [N,C,H*W,4]. The order is
+            (top,left,bottom,right) for the last dimension.
         """
         return border_align(input, boxes, self.pool_size)
 

mmcv/ops/box_iou_rotated.py

@@ -14,18 +14,19 @@ def box_iou_rotated(bboxes1, bboxes2, mode='iou', aligned=False):
     of bboxes1 and bboxes2, otherwise the ious between each aligned pair of
     bboxes1 and bboxes2.
 
-    Arguments:
-        boxes1 (Tensor): rotated bboxes 1. \
-            It has shape (N, 5), indicating (x, y, w, h, theta) for each row.
-            Note that theta is in radian.
-        boxes2 (Tensor): rotated bboxes 2. \
-            It has shape (M, 5), indicating (x, y, w, h, theta) for each row.
-            Note that theta is in radian.
+    Args:
+        boxes1 (torch.Tensor): rotated bboxes 1. It has shape (N, 5),
+            indicating (x, y, w, h, theta) for each row. Note that theta is in
+            radian.
+        boxes2 (torch.Tensor): rotated bboxes 2. It has shape (M, 5),
+            indicating (x, y, w, h, theta) for each row. Note that theta is in
+            radian.
         mode (str): "iou" (intersection over union) or iof (intersection over
             foreground).
 
     Returns:
-        ious(Tensor): shape (N, M) if aligned == False else shape (N,)
+        torch.Tensor: Return the ious betweens boxes. If ``aligned`` is
+        ``False``, the shape of ious is (N, M) else (N,).
     """
     assert mode in ['iou', 'iof']
     mode_dict = {'iou': 0, 'iof': 1}

mmcv/ops/carafe.py

@@ -180,7 +180,8 @@ def backward(ctx, grad_output):
 class CARAFE(Module):
     """ CARAFE: Content-Aware ReAssembly of FEatures
 
-    Please refer to https://arxiv.org/abs/1905.02188 for more details.
+    Please refer to `CARAFE: Content-Aware ReAssembly of FEatures
+    <https://arxiv.org/abs/1905.02188>`_ for more details.
 
     Args:
         kernel_size (int): reassemble kernel size
@@ -211,8 +212,8 @@ class CARAFEPack(nn.Module):
     compressor 2) content encoder 3) CARAFE op.
 
     Official implementation of ICCV 2019 paper
-    CARAFE: Content-Aware ReAssembly of FEatures
-    Please refer to https://arxiv.org/abs/1905.02188 for more details.
+    `CARAFE: Content-Aware ReAssembly of FEatures
+    <https://arxiv.org/abs/1905.02188>`_.
 
     Args:
         channels (int): input feature channels

mmcv/ops/cc_attention.py

@@ -53,10 +53,11 @@ def forward(self, x):
         """forward function of Criss-Cross Attention.
 
         Args:
-            x (Tensor): Input feature. \
-                shape (batch_size, in_channels, height, width)
+            x (torch.Tensor): Input feature with the shape of
+                (batch_size, in_channels, height, width).
+
         Returns:
-            Tensor: Output of the layer, with shape of \
+            torch.Tensor: Output of the layer, with the shape of
             (batch_size, in_channels, height, width)
         """
         B, C, H, W = x.size()

mmcv/ops/contour_expand.py

@@ -12,16 +12,16 @@ def contour_expand(kernel_mask, internal_kernel_label, min_kernel_area,
     """Expand kernel contours so that foreground pixels are assigned into
     instances.
 
-    Arguments:
-        kernel_mask (np.array or Tensor): The instance kernel mask with
+    Args:
+        kernel_mask (np.array or torch.Tensor): The instance kernel mask with
             size hxw.
-        internal_kernel_label (np.array or Tensor): The instance internal
+        internal_kernel_label (np.array or torch.Tensor): The instance internal
             kernel label with size hxw.
         min_kernel_area (int): The minimum kernel area.
         kernel_num (int): The instance kernel number.
 
     Returns:
-        label (list): The instance index map with size hxw.
+        list: The instance index map with size hxw.
     """
     assert isinstance(kernel_mask, (torch.Tensor, np.ndarray))
     assert isinstance(internal_kernel_label, (torch.Tensor, np.ndarray))

mmcv/ops/corner_pool.py

@@ -104,11 +104,13 @@ class CornerPool(nn.Module):
     Corner Pooling is a new type of pooling layer that helps a
     convolutional network better localize corners of bounding boxes.
 
-    Please refer to https://arxiv.org/abs/1808.01244 for more details.
+    Please refer to `CornerNet: Detecting Objects as Paired Keypoints
+    <https://arxiv.org/abs/1808.01244>`_ for more details.
+
     Code is modified from https://github.com/princeton-vl/CornerNet-Lite.
 
     Args:
-        mode(str): Pooling orientation for the pooling layer
+        mode (str): Pooling orientation for the pooling layer
 
             - 'bottom': Bottom Pooling
             - 'left': Left Pooling

mmcv/ops/furthest_point_sample.py

@@ -18,11 +18,11 @@ def forward(ctx, points_xyz: torch.Tensor,
                 num_points: int) -> torch.Tensor:
         """
         Args:
-            points_xyz (Tensor): (B, N, 3) where N > num_points.
+            points_xyz (torch.Tensor): (B, N, 3) where N > num_points.
             num_points (int): Number of points in the sampled set.
 
         Returns:
-             Tensor: (B, num_points) indices of the sampled points.
+            torch.Tensor: (B, num_points) indices of the sampled points.
         """
         assert points_xyz.is_contiguous()
 
@@ -56,11 +56,12 @@ def forward(ctx, points_dist: torch.Tensor,
                 num_points: int) -> torch.Tensor:
         """
         Args:
-            points_dist (Tensor): (B, N, N) Distance between each point pair.
+            points_dist (torch.Tensor): (B, N, N) Distance between each point
+                pair.
             num_points (int): Number of points in the sampled set.
 
         Returns:
-             Tensor: (B, num_points) indices of the sampled points.
+            torch.Tensor: (B, num_points) indices of the sampled points.
         """
         assert points_dist.is_contiguous()
 

mmcv/ops/fused_bias_leakyrelu.py

@@ -191,7 +191,8 @@ class FusedBiasLeakyReLU(nn.Module):
     """Fused bias leaky ReLU.
 
     This function is introduced in the StyleGAN2:
-    http://arxiv.org/abs/1912.04958
+    `Analyzing and Improving the Image Quality of StyleGAN
+    <http://arxiv.org/abs/1912.04958>`_
 
     The bias term comes from the convolution operation. In addition, to keep
     the variance of the feature map or gradients unchanged, they also adopt a
@@ -226,7 +227,8 @@ def fused_bias_leakyrelu(input, bias, negative_slope=0.2, scale=2**0.5):
     """Fused bias leaky ReLU function.
 
     This function is introduced in the StyleGAN2:
-    http://arxiv.org/abs/1912.04958
+    `Analyzing and Improving the Image Quality of StyleGAN
+    <http://arxiv.org/abs/1912.04958>`_
 
     The bias term comes from the convolution operation. In addition, to keep
     the variance of the feature map or gradients unchanged, they also adopt a

mmcv/ops/gather_points.py

@@ -15,11 +15,11 @@ def forward(ctx, features: torch.Tensor,
                 indices: torch.Tensor) -> torch.Tensor:
         """
         Args:
-            features (Tensor): (B, C, N) features to gather.
-            indices (Tensor): (B, M) where M is the number of points.
+            features (torch.Tensor): (B, C, N) features to gather.
+            indices (torch.Tensor): (B, M) where M is the number of points.
 
         Returns:
-            Tensor: (B, C, M) where M is the number of points.
+            torch.Tensor: (B, C, M) where M is the number of points.
         """
         assert features.is_contiguous()
         assert indices.is_contiguous()

mmcv/ops/group_points.py

@@ -67,12 +67,16 @@ def __init__(self,
     def forward(self, points_xyz, center_xyz, features=None):
         """
         Args:
-            points_xyz (Tensor): (B, N, 3) xyz coordinates of the features.
-            center_xyz (Tensor): (B, npoint, 3) coordinates of the centriods.
-            features (Tensor): (B, C, N) Descriptors of the features.
+            points_xyz (torch.Tensor): (B, N, 3) xyz coordinates of the
+                points.
+            center_xyz (torch.Tensor): (B, npoint, 3) coordinates of the
+                centriods.
+            features (torch.Tensor): (B, C, N) The features of grouped
+                points.
 
         Returns:
-            Tensor: (B, 3 + C, npoint, sample_num) Grouped feature.
+            torch.Tensor: (B, 3 + C, npoint, sample_num) Grouped
+                concatenated coordinates and features of points.
         """
         # if self.max_radius is None, we will perform kNN instead of ball query
         # idx is of shape [B, npoint, sample_num]

mmcv/ops/iou3d.py

@@ -17,7 +17,7 @@ def boxes_iou_bev(boxes_a, boxes_b):
         boxes_b (torch.Tensor): Input boxes b with shape (N, 5).
 
     Returns:
-        ans_iou (torch.Tensor): IoU result with shape (M, N).
+        torch.Tensor: IoU result with shape (M, N).
     """
     ans_iou = boxes_a.new_zeros(
         torch.Size((boxes_a.shape[0], boxes_b.shape[0])))

mmcv/ops/knn.py

@@ -8,6 +8,7 @@
 
 class KNN(Function):
     r"""KNN (CUDA) based on heap data structure.
+
     Modified from `PAConv <https://github.com/CVMI-Lab/PAConv/tree/main/
     scene_seg/lib/pointops/src/knnquery_heap>`_.
 
@@ -23,19 +24,19 @@ def forward(ctx,
         """
         Args:
             k (int): number of nearest neighbors.
-            xyz (Tensor): (B, N, 3) if transposed == False, else (B, 3, N).
-                xyz coordinates of the features.
-            center_xyz (Tensor, optional): (B, npoint, 3) if transposed ==
-                False, else (B, 3, npoint). centers of the knn query.
+            xyz (torch.Tensor): (B, N, 3) if transposed == False, else
+                (B, 3, N). xyz coordinates of the features.
+            center_xyz (torch.Tensor, optional): (B, npoint, 3) if transposed
+                is False, else (B, 3, npoint). centers of the knn query.
                 Default: None.
             transposed (bool, optional): whether the input tensors are
                 transposed. Should not explicitly use this keyword when
                 calling knn (=KNN.apply), just add the fourth param.
                 Default: False.
 
         Returns:
-            Tensor: (B, k, npoint) tensor with the indices of
-                the features that form k-nearest neighbours.
+            torch.Tensor: (B, k, npoint) tensor with the indices of the
+            features that form k-nearest neighbours.
         """
         assert (k > 0) & (k < 100), 'k should be in range(0, 100)'