DOC: clarify timing precision accessors and repair doctest example

quantecon/timings/__init__.py

@@ -4,4 +4,4 @@
 
 from .timings import float_precision, get_default_precision
 
-__all__ = ['float_precision', 'get_default_precision']
+__all__ = ['float_precision', 'get_default_precision']

quantecon/timings/timings.py

@@ -12,50 +12,58 @@
 def float_precision(precision=None):
     """
     Get or set the global float precision for timing outputs.
-    
+
     Parameters
     ----------
     precision : int, optional
-        Number of decimal places to display in timing outputs. 
+        Number of decimal places to display in timing outputs.
         If None, returns the current precision setting.
-        
+
     Returns
     -------
     int
         Current precision value if precision=None, otherwise None.
-        
+
     Examples
     --------
-    Get current precision:
+    Get the current precision:
+
     >>> import quantecon as qe
-    >>> current = qe.timings.float_precision()
-    >>> print(f"Current precision: {current}")
-
-    Set new precision:
+    >>> qe.timings.float_precision()
+    4
+
+    Set a new precision. All subsequent timing outputs use six decimal
+    places:
+
     >>> qe.timings.float_precision(6)
-    >>> # All subsequent timing outputs will use 6 decimal places
-
-    Reset to default:
+
+    Reset to the default:
+
     >>> qe.timings.float_precision(4)
     """
     global _DEFAULT_FLOAT_PRECISION
-    
+
     if precision is None:
         return _DEFAULT_FLOAT_PRECISION
-    
+
     if not isinstance(precision, int) or precision < 0:
         raise ValueError("precision must be a non-negative integer")
-    
+
     _DEFAULT_FLOAT_PRECISION = precision
 
 
 def get_default_precision():
     """
     Get the current default precision setting.
-
+
+    This is a read-only equivalent of calling :func:`float_precision` with
+    no argument; both return the same module-level value. It is the
+    accessor used internally by the timing utilities in
+    :mod:`quantecon.util.timing`, which only need to read the setting.
+
     Returns
     -------
     int
         Current default precision for timing outputs.
     """
-    return _DEFAULT_FLOAT_PRECISION
+    return _DEFAULT_FLOAT_PRECISION