Change findInstancesInHierarchy to return implicit top instance

* Change FIRRTL-internal API, affecting only one corner case
* Make API more "DWIM" and consistent with other methods
* Add test cases for findInstancesInHierarchy
* Update Scaladoc

1 files changed, 36 insertions, 5 deletions

diff --git a/src/test/scala/firrtlTests/analyses/InstanceGraphTests.scala b/src/test/scala/firrtlTests/analyses/InstanceGraphTests.scala
index e98c1895..eb62c564 100644
--- a/src/test/scala/firrtlTests/analyses/InstanceGraphTests.scala
+++ b/src/test/scala/firrtlTests/analyses/InstanceGraphTests.scala
@@ -1,12 +1,8 @@
 package firrtlTests.analyses
 
-import java.io._
-import org.scalatest._
-import org.scalatest.prop._
-import org.scalatest.Matchers._
 import firrtl.analyses.InstanceGraph
 import firrtl.graph.DiGraph
-import firrtl.Parser.parse
+import firrtl.WDefInstance
 import firrtl.passes._
 import firrtlTests._
 
@@ -39,6 +35,41 @@ circuit Top :
     getEdgeSet(graph) shouldBe Map("Top" -> Set("Child1", "Child2"), "Child1" -> Set("Child1a", "Child1b"), "Child2" -> Set(), "Child1a" -> Set(), "Child1b" -> Set())
   }
 
+  it should "find hierarchical instances correctly in disconnected hierarchies" in {
+    val input = """
+circuit Top :
+  module Top :
+    inst c of Child1
+  module Child1 :
+    skip
+
+  module Top2 :
+    inst a of Child2
+    inst b of Child3
+    skip
+  module Child2 :
+    inst a of Child2a
+    inst b of Child2b
+    skip
+  module Child2a :
+    skip
+  module Child2b :
+    skip
+  module Child3 :
+    skip
+"""
+
+    val circuit = ToWorkingIR.run(parse(input))
+    val iGraph = new InstanceGraph(circuit)
+    iGraph.findInstancesInHierarchy("Top") shouldBe Seq(Seq(WDefInstance("Top", "Top")))
+    iGraph.findInstancesInHierarchy("Child1") shouldBe Seq(Seq(WDefInstance("Top", "Top"), WDefInstance("c", "Child1")))
+    iGraph.findInstancesInHierarchy("Top2") shouldBe Nil
+    iGraph.findInstancesInHierarchy("Child2") shouldBe Nil
+    iGraph.findInstancesInHierarchy("Child2a") shouldBe Nil
+    iGraph.findInstancesInHierarchy("Child2b") shouldBe Nil
+    iGraph.findInstancesInHierarchy("Child3") shouldBe Nil
+  }
+
   it should "recognize disconnected hierarchies" in {
     val input = """
 circuit Top :