[fbsync] add docstring for _log_api_usage_once (#5273)

Summary:
* add docstring for _log_api_usage_once

* lint

* rephrase

Reviewed By: kazhang

Differential Revision: D33927494

fbshipit-source-id: 95c33f2f0fb8b576ce5528cc98f33661556c4819

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

Author: 2 people

torchvision/utils.py

@@ -2,11 +2,11 @@
 import pathlib
 import warnings
 from types import FunctionType
-from typing import Any, Union, Optional, List, Tuple, BinaryIO
+from typing import Any, BinaryIO, List, Optional, Tuple, Union
 
 import numpy as np
 import torch
-from PIL import Image, ImageDraw, ImageFont, ImageColor
+from PIL import Image, ImageColor, ImageDraw, ImageFont
 
 __all__ = ["make_grid", "save_image", "draw_bounding_boxes", "draw_segmentation_masks", "draw_keypoints"]
 
@@ -388,6 +388,23 @@ def _generate_color_palette(num_masks: int):
 
 
 def _log_api_usage_once(obj: Any) -> None:
+
+    """
+    Logs API usage(module and name) within an organization.
+    In a large ecosystem, it's often useful to track the PyTorch and
+    TorchVision APIs usage. This API provides the similar functionality to the
+    logging module in the Python stdlib. It can be used for debugging purpose
+    to log which methods are used and by default it is inactive, unless the user
+    manually subscribes a logger via the `SetAPIUsageLogger method <https://github.com/pytorch/pytorch/blob/eb3b9fe719b21fae13c7a7cf3253f970290a573e/c10/util/Logging.cpp#L114>`_.
+    Please note it is triggered only once for the same API call within a process.
+    It does not collect any data from open-source users since it is no-op by default.
+    For more information, please refer to
+    * PyTorch note: https://pytorch.org/docs/stable/notes/large_scale_deployments.html#api-usage-logging;
+    * Logging policy: https://github.com/pytorch/vision/issues/5052;
+
+    Args:
+        obj (class instance or method): an object to extract info from.
+    """
     if not obj.__module__.startswith("torchvision"):
         return
     name = obj.__class__.__name__