message: docs(core): add note about not mutating multi provider arrays
  Adds a note to the provider docs that users shouldn't mutate an array that
  is returned from a `multi` provider, because it can cause unforeseen
  consequences in other parts of the app.
  Closes
  PR Close
diff: @@ -284,6 +284,23 @@ Search for [Constants in API documentation](api?type=const) to find more built-i
  </div>
  +<div class="alert is-helpful">
  +
  +Note that the reference to the array returned for a `multi` provider is shared between all the
  +places where the token is injected. We recommend avoiding mutations of the array (especially for
  +predefined tokens) as it may lead to unexpected behavior in other parts of the app that inject
  +the same token. You can prevent the value from being mutated by setting its type to `ReadonlyArray`.
  +
  +</div>
  +
  +You can use `ReadonlyArray` to type your `multi` provider, so TypeScript triggers an error in case
  +of unwanted array mutations:
  +
  +```
  +constructor(@Inject(MULTI_PROVIDER) multiProvider: ReadonlyArray<MultiProvider>) {
  +}
  +```
  +
  {@a tree-shakable-provider}
  {@a tree-shakable-providers}
  