[Doc] Update docstring for functions in misc

python/taichi/_logging.py

@@ -34,50 +34,74 @@ def set_logging_level(level):
     See also https://docs.taichi.graphics/lang/articles/contribution/utilities#logging.
 
     Args:
-        level (str): The string represents logging level.
+        level (str): The string represents logging level.\
             Effective levels include: 'trace', 'debug', 'info', 'warn', 'error', 'critical'.
 
-    Example:
-            >>> set_logging_level('debug')
+    Example::
 
-        If call this function, then everything below 'debug' will be effective,
-        and 'trace' won't since it's above debug.
+        >>> set_logging_level('debug')
     """
     ti_core.set_logging_level(level)
 
 
 def is_logging_effective(level):
-    """Check if the level is effective. The level below current level will be effective.
-        If not set by manual, the pre-set logging level is 'info'.
+    """Check if the specified logging level is effective.
+    All levels below current level will be effective.
+    The default level is 'info'.
 
     See also https://docs.taichi.graphics/lang/articles/contribution/utilities#logging.
 
     Args:
-        level (str): The string represents logging level.
+        level (str): The string represents logging level. \
             Effective levels include: 'trace', 'debug', 'info', 'warn', 'error', 'critical'.
 
     Returns:
-        Bool: Indicate whether the logging level is supported.
+        Bool: Indicate whether the logging level is effective.
 
-    Example:
-        If current level is 'info':
+    Example::
 
-            >>> print(ti.is_logging_effective("trace"))     # False
-            >>> print(ti.is_logging_effective("debug"))     # False
-            >>> print(ti.is_logging_effective("info"))      # True
-            >>> print(ti.is_logging_effective("warn"))      # True
-            >>> print(ti.is_logging_effective("error"))     # True
-            >>> print(ti.is_logging_effective("critical"))  # True
+        >>> # assume current level is 'info'
+        >>> print(ti.is_logging_effective("trace"))     # False
+        >>> print(ti.is_logging_effective("debug"))     # False
+        >>> print(ti.is_logging_effective("info"))      # True
+        >>> print(ti.is_logging_effective("warn"))      # True
+        >>> print(ti.is_logging_effective("error"))     # True
+        >>> print(ti.is_logging_effective("critical"))  # True
     """
     return ti_core.logging_effective(level)
 
 
+# ------------------------
+
 DEBUG = 'debug'
+"""The `str` 'debug', used for the `debug` logging level.
+"""
+# ------------------------
+
 TRACE = 'trace'
+"""The `str` 'trace', used for the `debug` logging level.
+"""
+# ------------------------
+
 INFO = 'info'
+"""The `str` 'info', used for the `info` logging level.
+"""
+# ------------------------
+
 WARN = 'warn'
+"""The `str` 'warn', used for the `warn` logging level.
+"""
+# ------------------------
+
 ERROR = 'error'
+"""The `str` 'error', used for the `error` logging level.
+"""
+# ------------------------
+
 CRITICAL = 'critical'
+"""The `str` 'critical', used for the `critical` logging level.
+"""
+# ------------------------
 
 supported_log_levels = [DEBUG, TRACE, INFO, WARN, ERROR, CRITICAL]
 

python/taichi/lang/misc.py

@@ -172,6 +172,12 @@
 type_factory_ = _ti_core.get_type_factory_instance()
 
 extension = _ti_core.Extension
+"""An instance of Taichi extension.
+
+The list of currently available extensions is ['sparse', 'async_mode', 'quant', \
+    'mesh', 'quant_basic', 'data64', 'adstack', 'bls', 'assertion', \
+        'extfunc', 'packed', 'dynamic_index'].
+"""
 
 
 def is_extension_supported(arch, ext):
@@ -189,8 +195,19 @@ def is_extension_supported(arch, ext):
 
 def reset():
     """Resets Taichi to its initial state.
+    This will destroy all the allocated fields and kernels, and restore
+    the runtime to its default configuration.
+
+    Example::
 
-    This would destroy all the fields and kernels.
+        >>> a = ti.field(ti.i32, shape=())
+        >>> a[None] = 1
+        >>> print("before reset: ", a)
+        before rest: 1
+        >>>
+        >>> ti.reset()
+        >>> print("after reset: ", a)
+        # will raise error because a is unavailable after reset.
     """
     impl.reset()
     global runtime
@@ -504,8 +521,10 @@ def parallelize(v):
 serialize = lambda: parallelize(1)
 
 
-def block_dim(v):
-    get_runtime().prog.current_ast_builder().block_dim(v)
+def block_dim(dim):
+    """Set the number of threads in a block to `dim`.
+    """
+    get_runtime().prog.current_ast_builder().block_dim(dim)
 
 
 def global_thread_idx():
@@ -545,7 +564,8 @@ def Tape(loss, clear_gradients=True):
         >>>         y[None] += x[I] ** a
         >>>
         >>> with ti.Tape(loss = y):
-        >>>     sum(2)"""
+        >>>     sum(2)
+    """
     impl.get_runtime().materialize()
     if len(loss.shape) != 0:
         raise RuntimeError(
@@ -564,7 +584,8 @@ def Tape(loss, clear_gradients=True):
 
 
 def clear_all_gradients():
-    """Set all fields' gradients to 0."""
+    """Set the gradients of all fields to zero.
+    """
     impl.get_runtime().materialize()
 
     def visit(node):