From 295315a5ec83dc3173d6ae2437c11e1d8414f774 Mon Sep 17 00:00:00 2001
From: Jim Lawson <ucbjrl@berkeley.edu>
Date: Fri, 27 Jan 2017 10:58:38 -0800
Subject: [PATCH] Provide package-level text to reduce ScalaDoc white space.
 (#432)

---
 build.sbt                                    |  7 +++++++
 root-doc.txt                                 | 14 ++++++++++++++
 src/main/scala/chisel3/compatibility.scala   |  5 +++--
 src/main/scala/chisel3/package.scala         |  3 +++
 src/main/scala/chisel3/testers/package.scala | 10 ++++++++++
 src/main/scala/chisel3/util/util.scala       |  3 +++
 6 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 root-doc.txt
 create mode 100644 src/main/scala/chisel3/testers/package.scala

diff --git a/build.sbt b/build.sbt
index a00500a1dc6..eeff709b4a3 100644
--- a/build.sbt
+++ b/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),
diff --git a/root-doc.txt b/root-doc.txt
new file mode 100644
index 00000000000..245b4d24c1b
--- /dev/null
+++ b/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.
diff --git a/src/main/scala/chisel3/compatibility.scala b/src/main/scala/chisel3/compatibility.scala
index a919e3b9ffe..d7ce7f2426f 100644
--- a/src/main/scala/chisel3/compatibility.scala
+++ b/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
diff --git a/src/main/scala/chisel3/package.scala b/src/main/scala/chisel3/package.scala
index 109bd14ed56..c3531f3a44c 100644
--- a/src/main/scala/chisel3/package.scala
+++ b/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
 
diff --git a/src/main/scala/chisel3/testers/package.scala b/src/main/scala/chisel3/testers/package.scala
new file mode 100644
index 00000000000..649ea3d779b
--- /dev/null
+++ b/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 {
+
+}
\ No newline at end of file
diff --git a/src/main/scala/chisel3/util/util.scala b/src/main/scala/chisel3/util/util.scala
index 812af21cc69..129e5d1a75b 100644
--- a/src/main/scala/chisel3/util/util.scala
+++ b/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. */