From 378b19f0114d66d1287fac51cddeef022ad817e5 Mon Sep 17 00:00:00 2001
From: Brett <brettgraham@gmail.com>
Date: Fri, 12 Jan 2024 11:01:19 -0500
Subject: [PATCH] add lazy_nodes to docs

---
 asdf/_asdf.py               |  4 +++-
 asdf/config.py              |  3 ++-
 asdf/lazy_nodes.py          | 33 ++++++++++++++++++++++++++++++---
 docs/asdf/developer_api.rst |  2 ++
 4 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/asdf/_asdf.py b/asdf/_asdf.py
index 701cb594b..80494fb14 100644
--- a/asdf/_asdf.py
+++ b/asdf/_asdf.py
@@ -1588,7 +1588,9 @@ def open_asdf(
     lazy_tree : bool, optional
         When `True` the ASDF tree will not be converted to custom objects
         when the file is loaded. Instead, objects will be "lazily" converted
-        only when they are accessed.
+        only when they are accessed. Note that the tree will not contain dict
+        and list instances for containers and instead return instances of classes
+        defined in `asdf.lazy_nodes`.
 
     custom_schema : str, optional
         Path to a custom schema file that will be used for a secondary
diff --git a/asdf/config.py b/asdf/config.py
index 9f7321216..421f26364 100644
--- a/asdf/config.py
+++ b/asdf/config.py
@@ -446,7 +446,8 @@ def lazy_tree(self):
         """
         Get configuration that controls if ASDF tree contents
         are lazily converted to custom objects or if all custom
-        objects are created when the file is opened.
+        objects are created when the file is opened. See the
+        ``lazy_tree` argument for `asdf.open`.
 
         Returns
         -------
diff --git a/asdf/lazy_nodes.py b/asdf/lazy_nodes.py
index ee458e546..18d17537c 100644
--- a/asdf/lazy_nodes.py
+++ b/asdf/lazy_nodes.py
@@ -1,3 +1,7 @@
+"""
+Objects that act like dict, list, OrderedDict but allow
+lazy conversion of tagged ASDF tree nodes to custom objects.
+"""
 import collections
 import inspect
 import warnings
@@ -52,7 +56,13 @@ def _convert(value, af_ref):
         obj = converter.from_yaml_tree(data, tag, sctx)
 
         if isinstance(obj, GeneratorType):
-            # TODO we can't quite do this for every instance
+            # We can't quite do this for every instance (hence the
+            # isgeneratorfunction check above). However it appears
+            # to work for most instances (it was only failing for
+            # the FractionWithInverse test which is covered by the
+            # above code). The code here should only be hit if the
+            # Converter.from_yaml_tree calls another function which
+            # is a generator.
             generator = obj
             obj = next(generator)
             for _ in generator:
@@ -71,10 +81,17 @@ def __init__(self, data=None, af_ref=None):
 
     @property
     def tagged(self):
+        """
+        Return the tagged tree backing this node
+        """
         return self.data
 
 
 class AsdfListNode(AsdfNode, collections.UserList):
+    """
+    An `AsdfNode` subclass that acts like a ``list``.
+    """
+
     def __init__(self, data=None, af_ref=None):
         if data is None:
             data = []
@@ -83,6 +100,8 @@ def __init__(self, data=None, af_ref=None):
 
     @property
     def __class__(self):
+        # this is necessary to allow this class to pass
+        # an isinstance(list) check without inheriting from list.
         return list
 
     def __copy__(self):
@@ -140,9 +159,11 @@ def __getitem__(self, key):
         return value
 
 
-# dict is required here so TaggedDict doesn't convert this to a dict
-# and so that json.dumps will work for this node TODO add test
 class AsdfDictNode(AsdfNode, collections.UserDict):
+    """
+    An `AsdfNode` subclass that acts like a ``dict``.
+    """
+
     def __init__(self, data=None, af_ref=None):
         if data is None:
             data = {}
@@ -151,6 +172,8 @@ def __init__(self, data=None, af_ref=None):
 
     @property
     def __class__(self):
+        # this is necessary to allow this class to pass
+        # an isinstance(dict) check without inheriting from dict.
         return dict
 
     def __copy__(self):
@@ -206,6 +229,10 @@ def __getitem__(self, key):
 
 
 class AsdfOrderedDictNode(AsdfDictNode):
+    """
+    An `AsdfNode` subclass that acts like a ``collections.OrderedDict``.
+    """
+
     def __init__(self, data=None, af_ref=None):
         if data is None:
             data = collections.OrderedDict()
diff --git a/docs/asdf/developer_api.rst b/docs/asdf/developer_api.rst
index b04999733..7f0515d8e 100644
--- a/docs/asdf/developer_api.rst
+++ b/docs/asdf/developer_api.rst
@@ -32,3 +32,5 @@ to create their own custom ASDF types and extensions.
     :no-inheritance-diagram:
 
 .. automodapi:: asdf.testing.helpers
+
+.. automodapi:: asdf.lazy_nodes