Restore Port to public API and deprecate (#2302)

Also clean up deprecation warnings for replacement APIs and add
clarifying ScalaDoc.

5 files changed, 68 insertions, 10 deletions

diff --git a/core/src/main/scala/chisel3/BlackBox.scala b/core/src/main/scala/chisel3/BlackBox.scala
index 38b08193..ec5de0cd 100644
--- a/core/src/main/scala/chisel3/BlackBox.scala
+++ b/core/src/main/scala/chisel3/BlackBox.scala
@@ -8,6 +8,7 @@ import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl._
 import chisel3.internal.throwException
 import chisel3.internal.sourceinfo.{SourceInfo, UnlocatableSourceInfo}
+import scala.annotation.nowarn
 
 package internal {
 
@@ -61,6 +62,7 @@ package experimental {
     * }}}
     * @note The parameters API is experimental and may change
     */
+  @nowarn("msg=class Port") // delete when Port becomes private
   abstract class ExtModule(val params: Map[String, Param] = Map.empty[String, Param]) extends BaseBlackBox {
     private[chisel3] override def generateComponent(): Option[Component] = {
       require(!_closed, "Can't generate module more than once")
@@ -134,6 +136,7 @@ package experimental {
   * }}}
   * @note The parameters API is experimental and may change
   */
+@nowarn("msg=class Port") // delete when Port becomes private
 abstract class BlackBox(val params: Map[String, Param] = Map.empty[String, Param])(implicit compileOptions: CompileOptions) extends BaseBlackBox {
 
   // Find a Record port named "io" for purposes of stripping the prefix
diff --git a/core/src/main/scala/chisel3/Data.scala b/core/src/main/scala/chisel3/Data.scala
index d67a3af6..2bca5f98 100644
--- a/core/src/main/scala/chisel3/Data.scala
+++ b/core/src/main/scala/chisel3/Data.scala
@@ -154,13 +154,58 @@ package experimental {
       **/
     def checkTypeEquivalence(x: Data, y: Data): Boolean = x.typeEquivalent(y)
 
-    // Returns the top-level module ports
-    // TODO: maybe move to something like Driver or DriverUtils, since this is mainly for interacting
-    // with compiled artifacts (vs. elaboration-time reflection)?
+    /** Returns the ports of a module
+      * {{{
+      * class MyModule extends Module {
+      *   val io = IO(new Bundle {
+      *     val in = Input(UInt(8.W))
+      *     val out = Output(Vec(2, UInt(8.W)))
+      *   })
+      *   val extra = IO(Input(UInt(8.W)))
+      *   val delay = RegNext(io.in)
+      *   io.out(0) := delay
+      *   io.out(1) := delay + extra
+      * }
+      * val mod = Module(new MyModule)
+      * DataMirror.modulePorts(mod)
+      * // returns: Seq(
+      * //   "clock" -> mod.clock,
+      * //   "reset" -> mod.reset,
+      * //   "io" -> mod.io,
+      * //   "extra" -> mod.extra
+      * // )
+      * }}}
+      */
     def modulePorts(target: BaseModule): Seq[(String, Data)] = target.getChiselPorts
 
-    /** Returns all module ports with underscore-qualified names
-      * return includes [[Module.clock]] and [[Module.reset]]
+    /** Returns a recursive representation of a module's ports with underscore-qualified names
+      * {{{
+      * class MyModule extends Module {
+      *   val io = IO(new Bundle {
+      *     val in = Input(UInt(8.W))
+      *     val out = Output(Vec(2, UInt(8.W)))
+      *   })
+      *   val extra = IO(Input(UInt(8.W)))
+      *   val delay = RegNext(io.in)
+      *   io.out(0) := delay
+      *   io.out(1) := delay + extra
+      * }
+      * val mod = Module(new MyModule)
+      * DataMirror.fullModulePorts(mod)
+      * // returns: Seq(
+      * //   "clock" -> mod.clock,
+      * //   "reset" -> mod.reset,
+      * //   "io" -> mod.io,
+      * //   "io_out" -> mod.io.out,
+      * //   "io_out_0" -> mod.io.out(0),
+      * //   "io_out_1" -> mod.io.out(1),
+      * //   "io_in" -> mod.io.in,
+      * //   "extra" -> mod.extra
+      * // )
+      * }}}
+      * @note The returned ports are redundant. An [[Aggregate]] port will be present along with all
+      *       of its children.
+      * @see [[DataMirror.modulePorts]] for a non-recursive representation of the ports.
       */
     def fullModulePorts(target: BaseModule): Seq[(String, Data)] = {
       def getPortNames(name: String, data: Data): Seq[(String, Data)] = Seq(name -> data) ++ (data match {
diff --git a/core/src/main/scala/chisel3/RawModule.scala b/core/src/main/scala/chisel3/RawModule.scala
index d8781ee0..e977d918 100644
--- a/core/src/main/scala/chisel3/RawModule.scala
+++ b/core/src/main/scala/chisel3/RawModule.scala
@@ -5,6 +5,7 @@ package chisel3
 import scala.collection.mutable.{ArrayBuffer, HashMap}
 import scala.util.Try
 import scala.language.experimental.macros
+import scala.annotation.nowarn
 import chisel3.experimental.BaseModule
 import chisel3.internal._
 import chisel3.internal.BaseModule.{ModuleClone, InstanceClone}
@@ -17,6 +18,7 @@ import _root_.firrtl.annotations.{IsModule, ModuleTarget}
   * This abstract base class is a user-defined module which does not include implicit clock and reset and supports
   * multiple IO() declarations.
   */
+@nowarn("msg=class Port") // delete when Port becomes private
 abstract class RawModule(implicit moduleCompileOptions: CompileOptions)
     extends BaseModule {
   //
@@ -35,10 +37,10 @@ abstract class RawModule(implicit moduleCompileOptions: CompileOptions)
   //
   // Other Internal Functions
   //
-  // For debuggers/testers, TODO: refactor out into proper public API
   private var _firrtlPorts: Option[Seq[firrtl.Port]] = None
-  @deprecated("Use DataMirror.fullModulePorts instead. this API will be removed in Chisel 3.6", "Chisel 3.5")
-  lazy val getPorts = _firrtlPorts.get
+
+  @deprecated("Use DataMirror.modulePorts instead. this API will be removed in Chisel 3.6", "Chisel 3.5")
+  lazy val getPorts: Seq[Port] = _firrtlPorts.get
 
   val compileOptions = moduleCompileOptions
 
diff --git a/core/src/main/scala/chisel3/internal/firrtl/Converter.scala b/core/src/main/scala/chisel3/internal/firrtl/Converter.scala
index 1dc52823..ac784882 100644
--- a/core/src/main/scala/chisel3/internal/firrtl/Converter.scala
+++ b/core/src/main/scala/chisel3/internal/firrtl/Converter.scala
@@ -7,10 +7,11 @@ import chisel3.internal.sourceinfo.{NoSourceInfo, SourceInfo, SourceLine, Unloca
 import firrtl.{ir => fir}
 import chisel3.internal.{HasId, castToInt, throwException}
 
-import scala.annotation.tailrec
+import scala.annotation.{nowarn, tailrec}
 import scala.collection.immutable.Queue
 import scala.collection.immutable.LazyList // Needed for 2.12 alias
 
+@nowarn("msg=class Port") // delete when Port becomes private
 private[chisel3] object Converter {
   // TODO modeled on unpack method on Printable, refactor?
   def unpack(pable: Printable, ctx: Component): (String, Seq[Arg]) = pable match {
diff --git a/core/src/main/scala/chisel3/internal/firrtl/IR.scala b/core/src/main/scala/chisel3/internal/firrtl/IR.scala
index 3279e9b9..e3ea42c3 100644
--- a/core/src/main/scala/chisel3/internal/firrtl/IR.scala
+++ b/core/src/main/scala/chisel3/internal/firrtl/IR.scala
@@ -13,6 +13,7 @@ import _root_.firrtl.annotations.Annotation
 
 import scala.collection.immutable.NumericRange
 import scala.math.BigDecimal.RoundingMode
+import scala.annotation.nowarn
 
 
 private[chisel3] case class PrimOp(name: String) {
@@ -789,6 +790,7 @@ private[chisel3] case class DefRegInit(sourceInfo: SourceInfo, id: Data, clock:
 private[chisel3] case class DefMemory(sourceInfo: SourceInfo, id: HasId, t: Data, size: BigInt) extends Definition
 private[chisel3] case class DefSeqMemory(sourceInfo: SourceInfo, id: HasId, t: Data, size: BigInt, readUnderWrite: fir.ReadUnderWrite.Value) extends Definition
 private[chisel3] case class DefMemPort[T <: Data](sourceInfo: SourceInfo, id: T, source: Node, dir: MemPortDirection, index: Arg, clock: Arg) extends Definition
+@nowarn("msg=class Port") // delete when Port becomes private
 private[chisel3] case class DefInstance(sourceInfo: SourceInfo, id: BaseModule, ports: Seq[Port]) extends Definition
 private[chisel3] case class WhenBegin(sourceInfo: SourceInfo, pred: Arg) extends Command
 private[chisel3] case class WhenEnd(sourceInfo: SourceInfo, firrtlDepth: Int, hasAlt: Boolean = false) extends Command
@@ -799,7 +801,9 @@ private[chisel3] case class BulkConnect(sourceInfo: SourceInfo, loc1: Node, loc2
 private[chisel3] case class Attach(sourceInfo: SourceInfo, locs: Seq[Node]) extends Command
 private[chisel3] case class ConnectInit(sourceInfo: SourceInfo, loc: Node, exp: Arg) extends Command
 private[chisel3] case class Stop(id: stop.Stop, sourceInfo: SourceInfo, clock: Arg, ret: Int) extends Definition
-private[chisel3] case class Port(id: Data, dir: SpecifiedDirection)
+// Note this is just deprecated which will cause deprecation warnings, use @nowarn
+@deprecated("This API should never have been public, for Module port reflection, use DataMirror.modulePorts", "Chisel 3.5")
+case class Port(id: Data, dir: SpecifiedDirection)
 private[chisel3] case class Printf(id: printf.Printf, sourceInfo: SourceInfo, clock: Arg, pable: Printable) extends Definition
 private[chisel3] object Formal extends Enumeration {
   val Assert = Value("assert")
@@ -808,12 +812,15 @@ private[chisel3] object Formal extends Enumeration {
 }
 private[chisel3] case class Verification[T <: VerificationStatement](id: T, op: Formal.Value, sourceInfo: SourceInfo, clock: Arg,
                         predicate: Arg, message: String) extends Definition
+@nowarn("msg=class Port") // delete when Port becomes private
 private[chisel3] abstract class Component extends Arg {
   def id: BaseModule
   def name: String
   def ports: Seq[Port]
 }
+@nowarn("msg=class Port") // delete when Port becomes private
 private[chisel3] case class DefModule(id: RawModule, name: String, ports: Seq[Port], commands: Seq[Command]) extends Component
+@nowarn("msg=class Port") // delete when Port becomes private
 private[chisel3] case class DefBlackBox(id: BaseBlackBox, name: String, ports: Seq[Port], topDir: SpecifiedDirection, params: Map[String, Param]) extends Component
 
 case class Circuit(name: String, components: Seq[Component], annotations: Seq[ChiselAnnotation], renames: RenameMap) {