From 877633cd04c857b03422428951bf9bc825fa3d87 Mon Sep 17 00:00:00 2001
From: Xuehai Pan <XuehaiPan@pku.edu.cn>
Date: Fri, 29 Jul 2022 15:37:11 +0800
Subject: [PATCH] docs(core/utils): update docstrings for `NA`

Signed-off-by: Xuehai Pan <XuehaiPan@pku.edu.cn>
---
 README.md            | 22 +++++++++++++++++++++-
 nvitop/core/utils.py | 23 ++++++++++++++++++++---
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 996dbac..27c603d 100644
--- a/README.md
+++ b/README.md
@@ -991,7 +991,27 @@ In [18]: nvidia1_snapshot.bar1_memory_info  # snapshot will automatically retrie
 Out[18]: MemoryInfo(total=268435456, free=257622016, used=10813440)
 ```
 
-**NOTE:** Some entry values may be `'N/A'` (type: `NaType`, subclass of `str`) when the corresponding resources are not applicable. You can use `entry != 'N/A'` conditions to avoid exceptions. It's safe to use `float(entry)` for numbers while `NaType` will be converted to `math.nan`. For example:
+**NOTE:** Some entry values may be `'N/A'` (type: `NaType`, subclass of `str`) when the corresponding resources are not applicable. The `NA` value supports arithmetic operations. It acts like `math.nan: float`.
+
+```python
+>>> from nvitop import NA
+>>> NA
+'N/A'
+>>> 'memory usage: {}'.format(NA)  # NA is an instance of `str`
+'memory usage: N/A'
+>>> NA + 'str'
+'N/Astr'
+>>> float(NA)           # explicit conversion to float (`math.nan`)
+nan
+>>> NA + 1              # auto-casting to float
+nan
+>>> NA * 1024           # auto-casting to float
+nan
+>>> NA / (1024 * 1024)  # auto-casting to float
+nan
+```
+
+You can use `entry != 'N/A'` conditions to avoid exceptions. It's safe to use `float(entry)` for numbers while `NaType` will be converted to `math.nan`. For example:
 
 ```python
 memory_used: Union[int, NaType] = device.memory_used()            # memory usage in bytes or `'N/A'`
diff --git a/nvitop/core/utils.py b/nvitop/core/utils.py
index 5a55235..3f568fc 100644
--- a/nvitop/core/utils.py
+++ b/nvitop/core/utils.py
@@ -103,6 +103,23 @@ class NaType(str):
     The :const:`NA` instance behaves like a :class:`str` instance (:const:`'N/A'`) when doing string
     manipulation (e.g. concatenation). For arithmetic operations, for example :code:`NA / 1024 / 1024`,
     it acts like the :data:`math.nan`.
+
+    Examples:
+
+        >>> NA
+        'N/A'
+        >>> 'memory usage: {}'.format(NA)  # NA is an instance of `str`
+        'memory usage: N/A'
+        >>> NA + 'str'
+        'N/Astr'
+        >>> float(NA)           # explicit conversion to float (`math.nan`)
+        nan
+        >>> NA + 1              # auto-casting to float
+        nan
+        >>> NA * 1024           # auto-casting to float
+        nan
+        >>> NA / (1024 * 1024)  # auto-casting to float
+        nan
     """
 
     def __new__(cls) -> 'NaType':
@@ -382,17 +399,17 @@ class NaType(str):
     def __round__(self, ndigits: Optional[int] = None) -> Union[int, float]:
         """Rounds :const:`nvitop.NA` to ``ndigits`` decimal places, defaulting to :const:`0`.
 
-        If ``ndigits`` is omitted or :data:`None` or :const:`0`, returns :const:`0`, otherwise returns :data:`math.nan`.
+        If ``ndigits`` is omitted or :data:`None`, returns :const:`0`, otherwise returns :data:`math.nan`.
 
         >>> round(NA)
         0
         >>> round(NA, 0)
-        0
+        nan
         >>> round(NA, 1)
         nan
         """
 
-        if ndigits is None or ndigits == 0:
+        if ndigits is None:
             return int(self)
         return round(float(self), ndigits)