• Martin Atkins's avatar
    core: Document that TransformRoot must produce coalescable node · 0fc51abe
    Martin Atkins authored
    We use a non-pointer value for this particular node, which means that
    there can never be two root nodes in the same graph: the graph
    implementation will just coalesce them together when a second one is added.
    
    Our resource expansion code is relying on that coalescing so that it can
    subsume together multiple graphs for different modules instances into a
    single mega-graph with all instances across all module instances, with
    any root nodes coalescing together to produce a single root.
    
    This also updates one of the context tests that exercises resource
    expansion so that it will generate multiple resource instance nodes per
    module and thus potentially have multiple roots to coalesce together.
    However, we aren't currently explicitly validating the return values from
    DynamicExpand and so this test doesn't actually fail if the coalescing
    doesn't happen. We may choose to validate the DynamicExpand result in a
    later commit in order to make it more obvious if future modifications fail
    to uphold this invariant.
    0fc51abe