Document undocumented parameters (#3299)

* Document undodcumented parameters

* remove setup.cfg changes

* Properly pass normalize down instead of deprecating it

* Fix flake8

* Add new CI check

* Fix type spec

* Leave normalize be part of kwargs

Co-authored-by: Vasilis Vryniotis <[email protected]>

Author: NicolasHug

.circleci/config.yml

@@ -120,6 +120,16 @@ jobs:
             pip install --user --progress-bar off --editable .
             mypy --config-file mypy.ini
 
+  docstring_parameters_sync:
+    docker:
+      - image: circleci/python:3.7
+    steps:
+      - checkout
+      - run:
+          command: |
+            pip install --user pydocstyle
+            pydocstyle
+
   clang_format:
     docker:
       - image: circleci/python:3.7
@@ -1167,6 +1177,7 @@ workflows:
           - build_docs
       - python_lint
       - python_type_check
+      - docstring_parameters_sync
       - clang_format
       - torchhub_test
       - torch_onnx_test
@@ -1283,6 +1294,7 @@ workflows:
       - circleci_consistency
       - python_lint
       - python_type_check
+      - docstring_parameters_sync
       - clang_format
       - torchhub_test
       - torch_onnx_test

.circleci/config.yml.in

@@ -120,6 +120,16 @@ jobs:
             pip install --user --progress-bar off --editable .
             mypy --config-file mypy.ini
 
+  docstring_parameters_sync:
+    docker:
+      - image: circleci/python:3.7
+    steps:
+      - checkout
+      - run:
+          command: |
+            pip install --user pydocstyle
+            pydocstyle
+
   clang_format:
     docker:
       - image: circleci/python:3.7
@@ -778,6 +788,7 @@ workflows:
       {{ build_workflows(windows_latest_only=True) }}
       - python_lint
       - python_type_check
+      - docstring_parameters_sync
       - clang_format
       - torchhub_test
       - torch_onnx_test
@@ -796,6 +807,7 @@ workflows:
       - circleci_consistency
       - python_lint
       - python_type_check
+      - docstring_parameters_sync
       - clang_format
       - torchhub_test
       - torch_onnx_test

references/detection/coco_eval.py

@@ -239,6 +239,7 @@ def loadRes(self, resFile):
     """
     Load result file and return a result api object.
     Args:
+        self (obj): coco object with ground truth annotations
         resFile (str): file name of result file
     Returns:
     res (obj): result api object

setup.cfg

@@ -11,3 +11,6 @@ max-line-length = 120
 max-line-length = 120
 ignore = F401,E402,F403,W503,W504,F821
 exclude = venv
+
+[pydocstyle]
+select = D417 # Missing argument descriptions in the docstring

torchvision/datasets/video_utils.py

@@ -229,6 +229,7 @@ def compute_clips(self, num_frames, step, frame_rate=None):
         Args:
             num_frames (int): number of frames for the clip
             step (int): distance between two clips
+            frame_rate (int, optional): The frame rate
         """
         self.num_frames = num_frames
         self.step = step

torchvision/models/detection/_utils.py

@@ -86,6 +86,7 @@ def encode_boxes(reference_boxes, proposals, weights):
     Args:
         reference_boxes (Tensor): reference boxes
         proposals (Tensor): boxes to be encoded
+        weights (Tensor[4]): the weights for ``(x, y, w, h)``
     """
 
     # perform some unpacking to make it JIT-fusion friendly

torchvision/models/detection/backbone_utils.py

@@ -76,11 +76,18 @@ def resnet_fpn_backbone(
     Args:
         backbone_name (string): resnet architecture. Possible values are 'ResNet', 'resnet18', 'resnet34', 'resnet50',
              'resnet101', 'resnet152', 'resnext50_32x4d', 'resnext101_32x8d', 'wide_resnet50_2', 'wide_resnet101_2'
+        pretrained (bool): If True, returns a model with backbone pre-trained on Imagenet
         norm_layer (torchvision.ops): it is recommended to use the default value. For details visit:
             (https://github.com/facebookresearch/maskrcnn-benchmark/issues/267)
-        pretrained (bool): If True, returns a model with backbone pre-trained on Imagenet
         trainable_layers (int): number of trainable (not frozen) resnet layers starting from final block.
             Valid values are between 0 and 5, with 5 meaning all backbone layers are trainable.
+        returned_layers (list of int): The layers of the network to return. Each entry must be in ``[1, 4]``.
+            By default all layers are returned.
+        extra_blocks (ExtraFPNBlock or None): if provided, extra operations will
+            be performed. It is expected to take the fpn features, the original
+            features and the names of the original features as input, and returns
+            a new list of feature maps and their corresponding names. By
+            default a ``LastLevelMaxPool`` is used.
     """
     backbone = resnet.__dict__[backbone_name](
         pretrained=pretrained,

torchvision/models/quantization/googlenet.py

@@ -29,6 +29,7 @@ def googlenet(pretrained=False, progress=True, quantize=False, **kwargs):
     Args:
         pretrained (bool): If True, returns a model pre-trained on ImageNet
         progress (bool): If True, displays a progress bar of the download to stderr
+        quantize (bool): If True, return a quantized version of the model
         aux_logits (bool): If True, adds two auxiliary branches that can improve training.
             Default: *False* when pretrained is True otherwise *True*
         transform_input (bool): If True, preprocesses the input according to the method with which it

torchvision/models/quantization/inception.py

@@ -38,6 +38,7 @@ def inception_v3(pretrained=False, progress=True, quantize=False, **kwargs):
     Args:
         pretrained (bool): If True, returns a model pre-trained on ImageNet
         progress (bool): If True, displays a progress bar of the download to stderr
+        quantize (bool): If True, return a quantized version of the model
         aux_logits (bool): If True, add an auxiliary branch that can improve training.
             Default: *True*
         transform_input (bool): If True, preprocesses the input according to the method with which it

torchvision/models/quantization/resnet.py

@@ -143,6 +143,7 @@ def resnet18(pretrained=False, progress=True, quantize=False, **kwargs):
     Args:
         pretrained (bool): If True, returns a model pre-trained on ImageNet
         progress (bool): If True, displays a progress bar of the download to stderr
+        quantize (bool): If True, return a quantized version of the model
     """
     return _resnet('resnet18', QuantizableBasicBlock, [2, 2, 2, 2], pretrained, progress,
                    quantize, **kwargs)
@@ -155,6 +156,7 @@ def resnet50(pretrained=False, progress=True, quantize=False, **kwargs):
     Args:
         pretrained (bool): If True, returns a model pre-trained on ImageNet
         progress (bool): If True, displays a progress bar of the download to stderr
+        quantize (bool): If True, return a quantized version of the model
     """
     return _resnet('resnet50', QuantizableBottleneck, [3, 4, 6, 3], pretrained, progress,
                    quantize, **kwargs)
@@ -167,6 +169,7 @@ def resnext101_32x8d(pretrained=False, progress=True, quantize=False, **kwargs):
     Args:
         pretrained (bool): If True, returns a model pre-trained on ImageNet
         progress (bool): If True, displays a progress bar of the download to stderr
+        quantize (bool): If True, return a quantized version of the model
     """
     kwargs['groups'] = 32
     kwargs['width_per_group'] = 8