Better documentation needed for `includeTransitiveInitialInvalidations`

[Friendseeker]

https://github.com/sbt/zinc/blob/1c809a60a11a710aa4b016aa28f7e8a44da68a98/internal/zinc-core/src/main/scala/sbt/internal/inc/IncrementalCommon.scala#L581-L610

Issue: It is hard to tell the purpose of reInvalidated. Ideally the need to include reInvalidated can be documented better.

Preferably we can also add a unit test to demonstrate why reInvalidated needs to be returned. Currently, if we only return newInvalidations, every zinc scripted test still passes.

[eed3si9n]

So something like

1. User change invalidates A1.scala
2. By some simple invalidation, A1.scala invalidates B1.scala, like trait inheritance. Maybe it changes the API of the code somehow?
3. B1.scala invalidates another code C1.scala due to the API change. This also changes the API of the code somehow?
4. This then invalidates A1.scala, maybe because one of the methods references the change API in C1.scala

We'd need to recompile A1.scala with *.class of new C1.scala on the classpath.

[Friendseeker]

Thanks. I will look into that case. I don't fully understand why A1.scala would not be invalidated anyways in the next cycle when invalidateAfterInternalCompilation is called. But I guess playing with an active debugger would answer all my questions.