Contributed graph extensions example confusion

[bubenheimer]

I am unable to make sense of the contributed graph extensions example in the documentation: (https://zacsweers.github.io/metro/dependency-graphs/#the-problem). I suspect the example is not quite right, but I may be missing something.

The example describes a parent graph being defined in a parent module, and hypothesizes about the supposedly somewhat viable option of defining a (non-contributed) graph extension in a child module without a dependency on the parent module.

Isn't this entirely impossible in the first place? The child module does not see the parent module's graph interface, but would need to reference it in an @Extends parameter in its (non-contributed) graph extension factory:

// Defined in child :login module
@DependencyGraph(LoggedInScope::class)
interface LoggedInGraph {
  @DependencyGraph.Factory
  fun interface Factory {
    // we don't actually see AppGraph from parent :app module here
    fun create(@Extends appGraph: AppGraph): LoggedInGraph
  }
}

I can see how contributed graph extensions might help with this problem, but this is not what the example describes.

[ZacSweers]

The section you linked is about contributed graph extensions, but your code snippet is using @DependencyGraph, can you clarify? The purpose of @ContributedGraphExtension is to work around the situation your describe, the "real" graph is generated as a nested member of the target (in this case) AppGraph.

[bubenheimer]

The documentation introduces contributed graph extensions as the way to address the separate problem of seeing :user-data's UserRepository from :login module. But the example does not even work without user-data. It's a false premise to justify a concept.

I don't care that much if/how to fix the docs, if you don't agree, I just took note when thinking about how to best structure my graphs and wanted to seek clarification.

[bubenheimer]

What you are saying is, the example introduces contributed graph extensions as a new concept, when it is already implicitly relying on them as a prerequisite, which is rather hard to follow.

[ZacSweers]

It's not "a false premise to justify a concept", nor do I understand the strong the word choice there. This pattern has existed in Anvil since 2021 and works fine, it seems you just don't understand the doc. Which is fine! Happy to help clarify if there's places that can be improved.

It would help if you were specific in what you are having an issue with if you want clarification. For example:

But the example does not even work without user-data.

Explain what you mean by "does not even work".

when it is already implicitly relying on them as a prerequisite, which is rather hard to follow.

@ContributesGraphExtension is not mentioned anywhere else in that doc prior to its section. The doc is intentionally structured to introduce graphs, then graph extensions, and finally contributed extensions. What does "it is already implicitly relying on them as a prerequisite" mean?

[bubenheimer]

Sorry, I didn't mean to imply strong wording, that was meant as a statement of formal reasoning.

Thank you for investing your time elaborating on clarifications, I understand the underpinnings of the example now and how it came about.

I think a difference between Anvil's example and Metro's is that using @MergeSubcomponent in :login (the equivalent of non-contributed graph extensions) does not require access to :app's @Component, so @ContributesSubcomponent (the equivalent of contributed graph extensions) is needed only to deal with :user-data. By contrast, in Metro, extending a graph requires access to the graph, I think, unless using contributed graph extensions. So, in Metro's example, one technically has to use @ContributesSubcomponent earlier than in Anvil's example, even if there were no :user-data. This makes the flow of argument in Metro's example less clear.

I believe the reason is the difference in Metro's approach to graph extensions vs. Dagger/Anvil's: Metro's extensions are less tightly coupled to the graph. Metro's approach to graph extensions is a sound approach. Just that example does not seem to carry over with the same degree of clarity from what I can tell.

Again, the example may be just fine to bring the point across, it just confused me when I really wanted to understand the details of its implementation. Most readers may not bother.

Metro is a wonderful library and I greatly value all the time and energy you invest in developing and supporting it!