From 0d0f06a2e42718cb6bd3560cd270f0608ba7cd39 Mon Sep 17 00:00:00 2001
From: Gabriele Galiero Casay <gabriele.galiero.casay@intel.com>
Date: Wed, 17 Mar 2021 11:37:49 +0100
Subject: [PATCH] Clamp specification refactoring (#4663)

* Refactor specification

* Complete detail description section

* Rewrite mathematical formula

* Fix range of values for min and max attributes

* Add note for conversion policy between float and integral type of input tensor

* Address review comments

* Fix typo in max attribute
* Remove redundant examples
---
 docs/ops/activation/Clamp_1.md | 53 ++++++++++++++++++++++------------
 1 file changed, 34 insertions(+), 19 deletions(-)

diff --git a/docs/ops/activation/Clamp_1.md b/docs/ops/activation/Clamp_1.md
index 8ee374fdf25..91dba4b0ab2 100644
--- a/docs/ops/activation/Clamp_1.md
+++ b/docs/ops/activation/Clamp_1.md
@@ -6,48 +6,63 @@
 
 **Short description**: *Clamp* operation represents clipping activation function.
 
+**Detailed description**:
+
+*Clamp* performs clipping operation over the input tensor element-wise. Element values of the output are within the range `[min, max]`.
+* Input values that are smaller than *min* are replaced with *min* value.
+* Input values that are greater than *max* are replaced with *max* value.
+* Input values within the range `[min, max]` remain unchanged.
+
+Let *min_value* and *max_value* be *min* and *max*, respectively. The mathematical formula of *Clamp* is as follows:
+\f[
+clamp( x_{i} )=\min\big( \max\left( x_{i}, min\_value \right), max\_value \big)
+\f]
+
 **Attributes**:
 
 * *min*
 
-  * **Description**: *min* is the lower bound of values in the output. Any value in the input that is smaller than the bound, is replaced with the *min* value. For example, *min* equal 10 means that any value in the input that is smaller than the bound, is replaced by 10.
-  * **Range of values**: non-negative positive floating point number
-  * **Type**: float
+  * **Description**: *min* is the lower bound of values in the output.
+  * **Range of values**: arbitrary floating point number
+  * **Type**: `float`
   * **Default value**: None
   * **Required**: *yes*
 
 * *max*
 
-  * **Description**: *max* is the upper bound of values in the output. Any value in the input that is greater than the bound, is replaced with the *max* value. For example, *max* equals 50 means that any value in the input that is greater than the bound, is replaced by 50.
-  * **Range of values**: positive floating point number
-  * **Type**: float
+  * **Description**: *max* is the upper bound of values in the output.
+  * **Range of values**: arbitrary floating point number
+  * **Type**: `float`
   * **Default value**: None
   * **Required**: *yes*
 
 **Inputs**:
 
-*   **1**: Multidimensional input tensor. Required.
+*   **1**: A tensor of type `T` and arbitrary shape. **Required**.
 
 **Outputs**:
 
-*   **1**: Multidimensional output tensor with shape and type matching the input tensor.
+*   **1**: A tensor of type `T` with same shape as input tensor.
 
-**Detailed description**:
+**Types**
 
-*Clamp* does the following with the input tensor element-wise:
-\f[
-clamp( x )=\left\{\begin{array}{ll}
-    max\_value \quad \mbox{if } \quad input( x )>max\_value \\
-    min\_value \quad \mbox{if } \quad input( x )
-\end{array}\right.
-\f]
+* *T*: any numeric type.
+*   **Note**: In case of integral numeric type, ceil is used to convert *min* from `float` to `T` and floor is used to convert *max* from `float` to `T`.
 
 **Example**
 
 ```xml
-<layer ... type="Clamp" ... >
+<layer id="1" name="clamp_node" type="Clamp">
     <data min="10" max="50" />
-    <input> ... </input>
-    <output> ... </output>
+    <input>
+        <port id="0">
+            <dim>256</dim>
+        </port>
+    </input>
+    <output>
+        <port id="1">
+            <dim>256</dim>
+        </port>
+    </output>
 </layer>
 ```