What happens when you "include" a module from another module in Dagger?

Question

The Dagger documentation page says:

To get the most out of compile-time validation, create a module that includes all of your application's modules.

This leave some questions to be answered:

• What is actually the effect of including other modules? (At least, it seem included modules do not need to be instantiated directly)
• Is it legal/possible to have one module included multiple times by different modules? What would happen then?

Answer 1

The documentation needs improvement.

Includes is a literal inclusion - all of the @Provides methods of included modules, fully transitively, are collected together and considered as (in effect) part of the analyzed module. So:

@Module(includes = BModule.class)
class AModule {
  @Provides A provideA(...) { ... }
}

@Module
class BModule {
  @Provides B provideB(...) { ... }
}

is functionally identical to

@Module
class JointModule {
  @Provides A provideA(...) { ... }
  @Provides B provideB(...) { ... }
}

Additionally, module inclusion collapses duplicates. So if you have:

@Module(includes = {BModule.class, CModule.class})
class AModule { ... }

@Module(includes = CModule.class)
class BModule { ... }

@Module
class CModule { ... }

it will result in a collection of bindings (de-duplicated) from AModule + BModule + CModule.