From 9995620bd8f4037f4a60d2a63ba075288d7982c5 Mon Sep 17 00:00:00 2001
From: Seth Tisue <seth@tisue.net>
Date: Sun, 13 Aug 2023 16:07:51 -0700
Subject: [PATCH] compiler plugin Scaladoc: document phase requirement

fixes #18381

[Cherry-picked 521ac731d65c660099838180eff8693d936cecc1]
---
 compiler/src/dotty/tools/dotc/plugins/Plugin.scala | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/compiler/src/dotty/tools/dotc/plugins/Plugin.scala b/compiler/src/dotty/tools/dotc/plugins/Plugin.scala
index 1baf3a06ad9e..30ef94239ac1 100644
--- a/compiler/src/dotty/tools/dotc/plugins/Plugin.scala
+++ b/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