Provide package-level text to reduce ScalaDoc white space. (#432)

build.sbt

@@ -126,6 +126,13 @@ lazy val chisel = (project in file(".")).
   dependsOn(chiselFrontend % "compile-internal;test-internal").
   settings(
     scalacOptions in Test ++= Seq("-language:reflectiveCalls"),
+    scalacOptions in Compile in doc ++= Seq(
+      "-diagrams",
+      "-diagrams-max-classes", "25",
+      "-doc-version", version.value,
+      "-doc-title", name.value,
+      "-doc-root-content", baseDirectory.value+"/root-doc.txt"
+    ),
     aggregate in doc := false,
     // Include macro classes, resources, and sources main JAR.
     mappings in (Compile, packageBin) <++= mappings in (coreMacros, Compile, packageBin),

root-doc.txt

@@ -0,0 +1,14 @@
+This is the documentation for Chisel.
+
+== Package structure ==
+
+The [[chisel3]] package presents the public API of Chisel.
+It contains the concrete core types [[chisel3.core.UInt `UInt`]], [[chisel3.core.SInt `SInt`]], [[chisel3.core.Bool `Bool`]], [[chisel3.core.FixedPoint `FixedPoint`]], [[chisel3.core.Clock `Clock`]], and [[chisel3.core.Reg `Reg`]],
+the abstract types [[chisel3.core.Bits `Bits`]], [[chisel3.core.Aggregate `Aggregate`]], and [[chisel3.core.Data `Data`]],
+and the aggregate types [[chisel3.core.Bundle `Bundle`]] and [[chisel3.core.Vec `Vec`]].
+
+The [[Chisel]] package is a compatibility layer that attempts to provide chisel2 compatibility in chisel3.
+
+Utility objects and methods are found in the [[chisel3.util `util`]] package.
+
+The [[chisel3.testers `testers`]] package defines the basic interface for chisel testers.

src/main/scala/chisel3/compatibility.scala

@@ -1,7 +1,8 @@
 // See LICENSE for license details.
 
-// Allows legacy users to continue using Chisel (capital C) package name while
-// moving to the more standard package naming convention chisel3 (lowercase c).
+/** The Chisel compatibility package allows legacy users to continue using the `Chisel` (capital C) package name
+  *  while moving to the more standard package naming convention `chisel3` (lowercase c).
+  */
 
 package object Chisel {     // scalastyle:ignore package.object.name
   import chisel3.internal.firrtl.Width

src/main/scala/chisel3/package.scala

@@ -1,5 +1,8 @@
 // See LICENSE for license details.
 
+/** The chisel3 package contains the chisel3 API.
+  * It maps core components into the public chisel3 namespace.
+  */
 package object chisel3 {    // scalastyle:ignore package.object.name
   import scala.language.implicitConversions
 

src/main/scala/chisel3/testers/package.scala

@@ -0,0 +1,10 @@
+// See LICENSE for license details.
+
+package chisel3
+
+/** The testers package provides the basic interface for chisel testers.
+  *
+  */
+package object testers {
+
+}

src/main/scala/chisel3/util/util.scala

@@ -2,6 +2,9 @@
 
 package chisel3
 
+/** The util package provides extensions to core chisel for common hardware components and utility functions.
+  *
+  */
 package object util {
 
   /** Synonyms, moved from main package object - maintain scope. */