Clarify doc and format code

Signed-off-by: Philippe Ombredanne <pombredanne@nexb.com>

Author: pombredanne

src/packagedcode/build.py

@@ -102,26 +102,26 @@ class BaseStarlarkManifestHandler(models.DatafileHandler):
     def assemble(cls, package_data, resource, codebase, package_adder):
         """
         Given a ``package_data`` PackageData found in the ``resource`` datafile
-        of the ``codebase``, assemble package their files and dependencies
-        from one or more datafiles.
+        of the ``codebase``, assemble and yield a Package with its files and
+        dependencies from one or more datafiles.
         """
-        datafile_path = resource.path
         # do we have enough to create a package?
         if package_data.purl:
             package = models.Package.from_package_data(
                 package_data=package_data,
-                datafile_path=datafile_path,
+                datafile_path=resource.path,
             )
 
             if TRACE:
-                logger_debug(f"build: assemble: package_data: {package_data.to_dict()}")
+                logger_debug(f"BaseStarlarkManifestHandler.assemble: package_data: {package_data.to_dict()}")
 
-            package.license_detections, package.declared_license_expression = \
-                get_license_detections_and_expression(
-                    package=package_data,
-                    resource=resource,
-                    codebase=codebase,
-                )
+            detections, expression = get_license_detections_and_expression(
+                package=package_data,
+                resource=resource,
+                codebase=codebase,
+            )
+            package.license_detections = detections
+            package.declared_license_expression = expression
 
             cls.assign_package_to_resources(
                 package=package,

src/packagedcode/licensing.py

@@ -385,8 +385,9 @@ def get_license_detection_mappings(
     package_license=True,
 ):
     """
-    Return a list of LicenseDetection objects by running license detection
-    on `location`. This performs similarly to `scancode.api.get_licenses`.
+    Return a list of LicenseDetection mappings by running license detection on
+    the file at ``location``. This performs license detection the same way as
+    with `scancode.api.get_licenses`.
     """
     license_detections = []
     detections = detect_licenses(
@@ -399,9 +400,11 @@ def get_license_detection_mappings(
 
     for detection in detections:
         # TODO: also return these?
+        # FIXME: How can we ever get a license detection WITHOUT an expression??
         if detection.license_expression is None:
             continue
 
+        # FIXME: why not honoring the arguments for include_text and license_text_diagnostics?
         license_detections.append(
             detection.to_dict(
                 include_text=True,