Documentation pattern - secondary constructors

No documentation file or test is named. Start by locating the macwire documentation entry point for constructors, then incorporate the secondary-constructor, Defaults, and factory patterns shown in the issue. Done means the pattern is documented in the appropriate guide and the examples are understandable in the surrounding documentation.

If you're wondering how to deal with multiple constructors with macwire here is a pattern.

So you have this X class that provides default implementations for some of its parameters:

class X(a: A, b: B, c: C, d: D) {
  // secondary constructor, providing defaults for C and D
  def this(a: A, b: B) = {
    this(a, b, new DefaultC, new DefaultD)
  }
}

This can also be written using default parameters (as long as DefaultC or DefaultD does not depend on a or b), but down the line that's the same:

// default parameters, which will be turned into secondary constructors
class X(a: A, b: B, c: C = new DefaultC, d: D = new DefaultD)

(Un)fortunately macwire only looks at the primary constructor (BTW something could be said in the documentation about why this is better).
To workaround that "limitation" here is an alternative:

class X(a: A, b: B, c: C, d: D) {
  // no secondary constructor
}

object X {
    import Defaults._

    def apply(a: A, b: B) : X = wire[X]

    trait Defaults {
       lazy val c = wire[DefaultC]
       lazy val d = wire[DefaultD]
    }
    object Defaults extends Defaults   
}

We can now re-use the defaults provided by X if we're interested in them:

class MyModule extends X.Defaults {
   lazy val a: A = wire[AImpl]
   lazy val b: B = wire[BImpl]
   lazy val x: X = wire[X]
}

Things can get a little more tricky if DefaultC needs some parameters that we're unable to provide. In that case we'll resort to factories:

object X {
    import Defaults._

    def apply(a: A, b: B, cDep: CDep) : X = { 
       val c = buildC(cDep)
       wire[X]
   }

    trait Defaults {
       def buildC(cDep: CDep) = wire[DefaultC]
       lazy val d = wire[DefaultD]
    }
    object Defaults extends Defaults   
}

And in your module

class MyModule extends X.Defaults {
   lazy val a: A = wire[AImpl]
   lazy val b: B = wire[BImpl]
   lazy val cDep: CDep = wire[CDepImpl]
   lazy val c: C = buildC(cDep)
   lazy val x: X = wire[X]
}