The purpose of TransitName is to improve the naming of some object created in a different scope by "transiting" the name from the outer scope to the inner scope.

Consider the example below. This shows three ways of instantiating MyModule and returning the IO. Normally, the instance will be named MyModule. However, it would be better if the instance was named using the name of the val that user provides for the returned IO. TransitName can then be used to "transit" the name from the IO to the module:

/* Assign the IO of a new MyModule instance to value "foo". The instance will be named "MyModule". */
val foo = Module(new MyModule).io

/* Assign the IO of a new MyModule instance to value "bar". The instance will be named "bar". */
val bar = {
  val x = Module(new MyModule)
  TransitName(x.io, x) // TransitName returns the first argument
}

/* Assign the IO of a new MyModule instance to value "baz". The instance will be named "baz_generated". */
val baz = {
  val x = Module(new MyModule)
  TransitName.withSuffix("_generated")(x.io, x) // TransitName returns the first argument
}

TransitName helps library writers following the Factory Method Pattern where modules may be instantiated inside an enclosing scope. For an example of this, see how the Queue factory uses TransitName in Decoupled.scala factory.