From 566857e894c3f8a3ec5c77e1a5b36289f4cc3a17 Mon Sep 17 00:00:00 2001 From: Gilles Dubochet Date: Fri, 4 Feb 2011 13:14:46 +0000 Subject: [scaladoc] Tweaks to `Generator` data structure... [scaladoc] Tweaks to `Generator` data structure, and additional documentation. No review. --- .../scala/tools/nsc/doc/doclet/Generator.scala | 22 ++++++++++++++-------- .../scala/tools/nsc/doc/doclet/Indexer.scala | 2 +- 2 files changed, 15 insertions(+), 9 deletions(-) (limited to 'src') 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 -- cgit v1.2.3