Backport "compiler plugin Scaladoc: document phase requirement" to LTS (

#19162)

Backports #18394 to the LTS branch.

PR submitted by the release tooling.
[skip ci]

compiler/src/dotty/tools/dotc/plugins/Plugin.scala

@@ -43,6 +43,9 @@ sealed trait Plugin {
 /** A standard plugin can be inserted into the normal compilation pipeline */
 trait StandardPlugin extends Plugin {
   /** Non-research plugins should override this method to return the phases
+   *
+   *  The phases returned must be freshly constructed (not reused
+   *  and returned again on subsequent calls).
    *
    *  @param options commandline options to the plugin.
    *  @return a list of phases to be added to the phase plan
@@ -56,6 +59,9 @@ trait StandardPlugin extends Plugin {
  */
 trait ResearchPlugin extends Plugin {
   /** Research plugins should override this method to return the new phase plan
+   *
+   *  Any plugin phases included in the plan must be freshly constructed (not reused
+   *  and returned again on subsequent calls).
    *
    *  @param options commandline options to the plugin, `-P:plugname:opt1,opt2` becomes List(opt1, opt2)
    *  @param plan the given phase plan