[scaladoc] Tweaks to `Generator` data structure...

[scaladoc] Tweaks to `Generator` data structure, and additional
documentation. No review.

2 files changed, 15 insertions, 9 deletions

diff --git a/src/compiler/scala/tools/nsc/doc/doclet/Generator.scala b/src/compiler/scala/tools/nsc/doc/doclet/Generator.scala
index 6e4986d7ec..2caf67ee78 100644
--- a/src/compiler/scala/tools/nsc/doc/doclet/Generator.scala
+++ b/src/compiler/scala/tools/nsc/doc/doclet/Generator.scala
@@ -3,22 +3,28 @@ package doclet
 
 import scala.collection._
 
-/** Hook into the documentation generation process.  The Doclet receives a model of the code being generated, and
-  * can then do whatever it wants with it. */
+/** Custom Scaladoc generators must implement the `Generator` class. A custom generator can be selected in Scaladoc
+  * using the `-doc-generator` command line option.
+  * The `Generator` class does not provide data about the documented code. A number of data provider traits can be used
+  * to configure what data is actually available to the generator:
+  *  - A `Universer` provides a `Universe` data structure representing the interfaces and comments of the documented
+  *    program.
+  *  - An `Indexer` provides precalculated indexing information about a universe.
+  * To implement this class only requires defining method `generateImpl`. */
 abstract class Generator {
 
-  val checks: mutable.Set[()=>Boolean] =
+  /** A series of tests that must be true before generation can be done. This is used by data provider traits to
+    * confirm that they have been correctly initialised before allowing generation to proceed. */
+  protected val checks: mutable.Set[()=>Boolean] =
     mutable.Set.empty[()=>Boolean]
 
-  /** Called after the model of the generated documentation is created */
+  /** Outputs documentation (as a side effect). */
   def generate: Unit = {
     assert(checks forall { check => check() })
     generateImpl
   }
 
-  def generateImpl: Unit
+  /** Outputs documentation (as a side effect). This method is called only if all `checks` are true. */
+  protected def generateImpl: Unit
 
 }
-
-
-
diff --git a/src/compiler/scala/tools/nsc/doc/doclet/Indexer.scala b/src/compiler/scala/tools/nsc/doc/doclet/Indexer.scala
index e58893e3b4..0cdd47182f 100644
--- a/src/compiler/scala/tools/nsc/doc/doclet/Indexer.scala
+++ b/src/compiler/scala/tools/nsc/doc/doclet/Indexer.scala
@@ -3,7 +3,7 @@ package doc
 package doclet
 
 /** A `Generator` may implement the `Indexer` trait to gain access to pre-calculated indexing information */
-trait Indexer extends Generator {
+trait Indexer extends Generator with Universer {
 
   protected var indexField: Index = null