Add some comments and docs to get_cres_link_objects()

numba_cuda/numba/cuda/dispatcher.py

@@ -43,16 +43,34 @@
 
 
 def get_cres_link_objects(cres):
+    """Given a compile result, return a set of all linkable code objects that
+    are required for it to be fully linked."""
+
     link_objects = set()
+
+    # The typemap of the function includes calls, so we can traverse it to find
+    # the references we need.
     for name, v in cres.fndesc.typemap.items():
+
+        # CUDADispatchers represent a call to a device function, so we need to
+        # look up the linkable code for those recursively.
         if isinstance(v, cuda_types.CUDADispatcher):
+            # We need to locate the signature of the call so we can find the
+            # correct overload.
             for call, sig in cres.fndesc.calltypes.items():
                 if isinstance(call, ir.Expr) and call.op == 'call':
+                    # There will likely be multiple calls in the typemap; we
+                    # can uniquely identify the relevant one using its SSA
+                    # name.
                     if call.func.name == name:
                         called_cres = v.dispatcher.overloads[sig.args]
                         called_link_objects = get_cres_link_objects(called_cres)
                         link_objects.update(called_link_objects)
 
+        # From this point onwards, we are only interested in ExternFunction
+        # declarations - these are the calls made directly in this function to
+        # them.
+
         if not isinstance(v, Function):
             continue