grc: Improve documentation of _lazy.py

Signed-off-by: Martin Braun <martin@gnuradio.org>
Signed-off-by: Jeff Long <willcode4@gmail.com>
(cherry picked from commit cce52e9dfd1ea6e0a081e824754422852e0872b1)
Signed-off-by: Jeff Long <willcode4@gmail.com>

1 files changed, 36 insertions, 2 deletions

diff --git a/grc/core/utils/descriptors/_lazy.py b/grc/core/utils/descriptors/_lazy.py
index 7d5c2c49c..e890be4f0 100644
--- a/grc/core/utils/descriptors/_lazy.py
+++ b/grc/core/utils/descriptors/_lazy.py
@@ -3,11 +3,40 @@
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 #
+"""
+Class method decorators.
+"""
 
 import functools
 
+# pylint: disable=too-few-public-methods,invalid-name
 
-class lazy_property(object):
+
+class lazy_property:
+    """
+    Class method decorator, similar to @property. This causes a method that is
+    declared as @lazy_property to be evaluated once, the first time it is called.
+    Subsequent calls to this property will always return the cached value.
+
+    Careful! Not suitable for properties that change at runtime.
+
+    Example:
+
+    >>> class Foo:
+    ...     def __init__(self):
+    ...         self.x = 5
+    ...
+    ...     @lazy_property
+    ...     def xyz(self):
+    ...         return complicated_slow_function(self.x)
+    ...
+    ...
+    >>> f = Foo()
+    >>> print(f.xyz) # Will give the result, but takes long to compute
+    >>> print(f.xyz) # Blazing fast!
+    >>> f.x = 7 # Careful! f.xyz will not be updated any more!
+    >>> print(f.xyz) # Blazing fast, but returns the same value as before.
+    """
 
     def __init__(self, func):
         self.func = func
@@ -19,10 +48,15 @@ class lazy_property(object):
         value = self.func(instance)
         setattr(instance, self.func.__name__, value)
         return value
+# pylint: enable=too-few-public-methods,invalid-name
 
 
 def nop_write(prop):
-    """Make this a property with a nop setter"""
+    """
+    Make this a property with a nop setter
+
+    Effectively, makes a property read-only, with no error on write.
+    """
 
     def nop(self, value):
         pass