From 90c8a58cca96595be5e8706d712ff664f7218979 Mon Sep 17 00:00:00 2001
From: Megvii Engine Team <megengine@megvii.com>
Date: Thu, 24 Feb 2022 22:50:43 +0800
Subject: [PATCH] docs(docstring): add pad docstring

GitOrigin-RevId: eaf6a874560de1298f09ad01d055fb56cea807f9
---
 imperative/python/megengine/functional/nn.py  | 43 +++++++++++++++--
 imperative/python/megengine/module/padding.py | 47 +++++++++++++++++--
 2 files changed, 84 insertions(+), 6 deletions(-)

diff --git a/imperative/python/megengine/functional/nn.py b/imperative/python/megengine/functional/nn.py
index 2c6eb32de..a5d069950 100644
--- a/imperative/python/megengine/functional/nn.py
+++ b/imperative/python/megengine/functional/nn.py
@@ -1894,9 +1894,46 @@ def pad(
     mode: str = "constant",
     constant_value: float = 0.0,
 ) -> Tensor:
-    """
-    Pad is python warpper for padding opr in megbrain, can padding in random one of the max 7 dimensions.
-    Supported constant, edge(replicate) and reflect mode, constatnt is the default mode.
+    r"""Pads the input tensor.
+
+    Args:
+        pad_width: A tuple. Each element in the tuple is the tuple of 2-elements,
+            the 2 elements represent the padding size on both sides of the current dimension, ``(front_offset, back_offset)``
+        mode: One of the following string values. Default: ``'constant'``
+
+            * ``'constant'``: Pads with a constant value.
+            * ``'reflect'``: Pads with the edge values of tensor.
+            * ``'replicate'``: Pads with the reflection of the tensor mirrored on the first and last values of the tensor along each axis.
+        constant_val: Fill value for ``'constant'`` padding. Default: 0
+
+    Examples:
+
+        >>> import numpy as np
+        >>> inp = Tensor([[1., 2., 3.],[4., 5., 6.]])
+        >>> inp
+        Tensor([[1. 2. 3.]
+         [4. 5. 6.]], device=xpux:0)
+        >>> F.nn.pad(inp, pad_width=((1, 1),), mode="constant")
+        Tensor([[0. 0. 0.]
+         [1. 2. 3.]
+         [4. 5. 6.]
+         [0. 0. 0.]], device=xpux:0)
+        >>> F.nn.pad(inp, pad_width=((1, 1),), mode="constant", constant_value=9)
+        Tensor([[9. 9. 9.]
+         [1. 2. 3.]
+         [4. 5. 6.]
+         [9. 9. 9.]], device=xpux:0)
+        >>> F.nn.pad(inp, pad_width=((1, 1), (1, 2)), mode="reflect")
+        Tensor([[5. 4. 5. 6. 5. 4.]
+         [2. 1. 2. 3. 2. 1.]
+         [5. 4. 5. 6. 5. 4.]
+         [2. 1. 2. 3. 2. 1.]], device=xpux:0)
+        >>> F.nn.pad(inp, pad_width=((1, 1), (1, 2)), mode="replicate")
+        Tensor([[1. 1. 2. 3. 3. 3.]
+         [1. 1. 2. 3. 3. 3.]
+         [4. 4. 5. 6. 6. 6.]
+         [4. 4. 5. 6. 6. 6.]], device=xpux:0)
+
     """
     p_offsets = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
 
diff --git a/imperative/python/megengine/module/padding.py b/imperative/python/megengine/module/padding.py
index 078daabc0..54fbdf973 100644
--- a/imperative/python/megengine/module/padding.py
+++ b/imperative/python/megengine/module/padding.py
@@ -5,9 +5,50 @@ from .module import Module
 
 
 class Pad(Module):
-    """
-    Pad is python warpper for padding opr in megbrain, can padding in random one of the max 7 dimensions.
-    Supported constant, edge(replicate) and reflect mode, constatnt is the default mode.
+    r"""Pads the input tensor.
+
+    Args:
+        pad_width: A tuple. Each element in the tuple is the tuple of 2-elements,
+            the 2 elements represent the padding size on both sides of the current dimension, ``(front_offset, back_offset)``
+        mode: One of the following string values. Default: ``'constant'``
+
+            * ``'constant'``: Pads with a constant value.
+            * ``'reflect'``: Pads with the edge values of tensor.
+            * ``'replicate'``: Pads with the reflection of the tensor mirrored on the first and last values of the tensor along each axis.
+        constant_val: Fill value for ``'constant'`` padding. Default: 0
+
+    Examples:
+
+        >>> import numpy as np
+        >>> inp = Tensor([[1., 2., 3.],[4., 5., 6.]])
+        >>> inp
+        Tensor([[1. 2. 3.]
+         [4. 5. 6.]], device=xpux:0)
+        >>> m = M.Pad(pad_width=((1, 1),), mode="constant")
+        >>> m(inp)
+        Tensor([[0. 0. 0.]
+         [1. 2. 3.]
+         [4. 5. 6.]
+         [0. 0. 0.]], device=xpux:0)
+        >>> m = M.Pad(pad_width=((1, 1),), mode="constant", constant_val=9)
+        >>> m(inp)
+        Tensor([[9. 9. 9.]
+         [1. 2. 3.]
+         [4. 5. 6.]
+         [9. 9. 9.]], device=xpux:0)
+        >>> m = M.Pad(pad_width=((1, 1), (1, 2)), mode="reflect")
+        >>> m(inp)
+        Tensor([[5. 4. 5. 6. 5. 4.]
+         [2. 1. 2. 3. 2. 1.]
+         [5. 4. 5. 6. 5. 4.]
+         [2. 1. 2. 3. 2. 1.]], device=xpux:0)
+        >>> m = M.Pad(pad_width=((1, 1), (1, 2)), mode="replicate")
+        >>> m(inp)
+        Tensor([[1. 1. 2. 3. 3. 3.]
+         [1. 1. 2. 3. 3. 3.]
+         [4. 4. 5. 6. 6. 6.]
+         [4. 4. 5. 6. 6. 6.]], device=xpux:0)
+
     """
 
     def __init__(
-- 
GitLab