From 15336c189e1b3080648fbd234bbf17bfe2e19890 Mon Sep 17 00:00:00 2001
From: Ed Slavich <eslavich@stsci.edu>
Date: Fri, 7 Aug 2020 09:44:46 -0400
Subject: [PATCH] Add missing docstrings and comments

---
 asdf/asdf.py     | 37 +++++++++++++++++++++++++++++++++++++
 asdf/yamlutil.py |  4 ++++
 2 files changed, 41 insertions(+)

diff --git a/asdf/asdf.py b/asdf/asdf.py
index 7a6ae2dd4..3547cc2f4 100644
--- a/asdf/asdf.py
+++ b/asdf/asdf.py
@@ -250,6 +250,19 @@ def __exit__(self, type, value, traceback):
         self.close()
 
     def _check_extensions(self, tree, strict=False):
+        """
+        Compare the user's installed extensions to metadata in the tree
+        and warn when a) an extension is missing or b) an extension is
+        present but the file was written with a later version of the
+        extension's package.
+
+        Parameters
+        ----------
+        tree : AsdfObject
+            Fully converted tree of custom types.
+        strict : bool, optional
+            Set to `True` to convert warnings to exceptions.
+        """
         if 'history' not in tree or not isinstance(tree['history'], dict) or \
                 'extensions' not in tree['history']:
             return
@@ -305,6 +318,21 @@ def _check_extensions(self, tree, strict=False):
                         warnings.warn(msg, AsdfWarning)
 
     def _process_extensions(self, requested_extensions):
+        """
+        Validate a list of extensions requested by the user and
+        add missing extensions registered with the current `AsdfConfig`.
+
+        Parameters
+        ----------
+        requested_extensions : object
+            May be any of the following: `asdf.extension.AsdfExtension`, `str`
+            extension URI, `asdf.extension.AsdfExtensionList` or a `list`
+            of URIs and/or extensions.
+
+        Returns
+        -------
+        list of asdf.extension.AsdfExtension
+        """
         if requested_extensions is None:
             requested_extensions = []
         elif isinstance(requested_extensions, (AsdfExtension, ExtensionProxy, str)):
@@ -336,6 +364,15 @@ def _get_extension(e):
         return extensions
 
     def _update_extension_history(self, serialization_context):
+        """
+        Update the extension metadata on this file's tree to reflect
+        extensions used during serialization.
+
+        Parameters
+        ----------
+        serialization_context : asdf.asdf.SerializationContext
+            The context that was used to serialize the tree.
+        """
         if serialization_context.version < versioning.NEW_HISTORY_FORMAT_MIN_VERSION:
             return
 
diff --git a/asdf/yamlutil.py b/asdf/yamlutil.py
index 41fbd0f7f..a3745bf75 100644
--- a/asdf/yamlutil.py
+++ b/asdf/yamlutil.py
@@ -331,6 +331,10 @@ def dump_tree(tree, fd, ctx, tree_finalizer=None, _serialization_context=None):
         extension metadata on the tagged tree before it is fully
         serialized to YAML.
     """
+    # The _serialization_context parameter allows AsdfFile to track
+    # what extensions were used when converting the tree's custom
+    # types.  In 3.0, it will be passed as the `ctx` instead of the
+    # AsdfFile itself.
     tags = None
     tree_type = ctx.type_index.from_custom_type(type(tree))
     if tree_type is not None: