Update doc and comments

Signed-off-by: Jono Yang <jyang@nexb.com>

Author: JonoYang

CHANGELOG.rst

@@ -60,6 +60,13 @@ Important API changes:
   under the ``venv`` subdirectory. You mus be aware of this if you use ScanCode
   from a git clone
 
+- ``DatafileHandler.assemble()``, ``DatafileHandler.assemble_from_many()``, and
+  the other ``.assemble()``` methods from the other Package handlers from
+  packagedcode, have been updated to yield Package items before Dependency or
+  Resource items. This is particulary important in the case where we are calling
+  the ``assemble()`` method outside of the scancode-toolkit context, where we
+  need to ensure that a Package exists before we assocate a Resource or
+  Dependency to it.
 
 Copyright detection:
 ~~~~~~~~~~~~~~~~~~~~

src/packagedcode/models.py

@@ -914,6 +914,12 @@ def assemble(cls, package_data, resource, codebase, package_adder=add_to_package
           not be further processed,
         - a Dependency to add to top-level dependencies
 
+        Package items must be yielded before Dependency or Resource items. This
+        is to ensure that a Package is created before we associate a Resource or
+        Dependency to a Package. This is particulary important in the case where
+        we are calling the `assemble()` method outside of the scancode-toolkit
+        context.
+
         The approach is to find and process all the neighboring related datafiles
          to this datafile at once.
 
@@ -1038,6 +1044,13 @@ def assemble_from_many(cls, pkgdata_resources, codebase, package_adder=add_to_pa
         This is a convenience method that subclasses can reuse when overriding
         `assemble()`
 
+        Like in ``DatafileHandler.assemble()``, Package items must be yielded
+        before Dependency or Resource items. This is to ensure that a Package is
+        created before we associate a Resource or Dependency to a Package. This
+        is particulary important in the case where we are calling the
+        ``assemble()`` method outside of the scancode-toolkit context, as
+        ``assemble()`` can call ``assemble_from_many()``.
+
         NOTE: ATTENTION!: this may not work well for datafile that yield
         multiple PackageData for unrelated Packages
         """