diff options
author | michelou <michelou@epfl.ch> | 2011-07-15 21:38:03 +0000 |
---|---|---|
committer | michelou <michelou@epfl.ch> | 2011-07-15 21:38:03 +0000 |
commit | 2621ee63285808785159a3c24c9e5a5a723b8b9c (patch) | |
tree | 15d5a0863a7759f7c2178e1c9d29402fc9cd6fb8 /src | |
parent | a4fb15861b271c41fba8382f3b55024b5fdc8155 (diff) | |
download | scala-2621ee63285808785159a3c24c9e5a5a723b8b9c.tar.gz scala-2621ee63285808785159a3c24c9e5a5a723b8b9c.tar.bz2 scala-2621ee63285808785159a3c24c9e5a5a723b8b9c.zip |
scaladoc fixes and improvements
Changes to scaladoc include:
- fixed transformation of Code(text) into HTML tag <code> - added tool
tips for deprecated entities (classes, methods) using the 'title'
attribute - added syntax highlighting of Scala source code in generated
<pre> blocks (CSS colors are defined in lib/template.css)
Here are several examples of highlighted Scala code:
scala.App
scala.Application
scala.Enumeration
scala.Function1
scala.Function2
scala.native
scala.Option
scala.Proxy
scala.specialized
scala.throws
scala.unchecked
scala.actors.Actor
scala.annotation.deprecatedName
scala.annotation.elidable
scala.annotation.switch
scala.collection.DefaultMap
scala.collection.JavaConversions
scala.collection.JavaConverters
scala.collection.LinearSeqLike
scala.collection.MapLike
scala.collection.SetLike
scala.collection.TraversableLike
scala.collection.immutable.NumericRange
scala.collection.immutable.Range
scala.collection.immutable.Stream
scala.collection.mutable.BufferLike
scala.concurrent.pilib
scala.io.Position
scala.reflect.BeanProperty
scala.reflect.Manifest
scala.testing.Benchmark
scala.util.DynamicVariable
scala.util.control.Breaks
scala.util.control.ControlThrowable
scala.util.control.Exception
scala.util.control.TailCalls
scala.util.logging.Logged
scala.util.parsing.combinator.testing.Tester
scala.util.parsing.json.JSON
scala.util.regexp.WordExp
scala.xml.factory.LoggedNodeFactory
scala.xml.parsing.ConstructingParser
Diffstat (limited to 'src')
24 files changed, 573 insertions, 185 deletions
diff --git a/src/compiler/scala/reflect/api/Trees.scala b/src/compiler/scala/reflect/api/Trees.scala index 5401962ea6..2addd401c9 100644 --- a/src/compiler/scala/reflect/api/Trees.scala +++ b/src/compiler/scala/reflect/api/Trees.scala @@ -356,20 +356,16 @@ trait Trees /*extends reflect.generic.Trees*/ { self: Universe => case class If(cond: Tree, thenp: Tree, elsep: Tree) extends TermTree - /** <p> - * Pattern matching expression (before explicitouter) - * Switch statements (after explicitouter) - * </p> - * <p> - * After explicitouter, cases will satisfy the following constraints: - * </p> - * <ul> - * <li>all guards are EmptyTree,</li> - * <li>all patterns will be either <code>Literal(Constant(x:Int))</code> - * or <code>Alternative(lit|...|lit)</code></li> - * <li>except for an "otherwise" branch, which has pattern - * <code>Ident(nme.WILDCARD)</code></li> - * </ul> + /** - Pattern matching expression (before explicitouter) + * - Switch statements (after explicitouter) + * + * After explicitouter, cases will satisfy the following constraints: + * + * - all guards are `EmptyTree`, + * - all patterns will be either `Literal(Constant(x:Int))` + * or `Alternative(lit|...|lit)` + * - except for an "otherwise" branch, which has pattern + * `Ident(nme.WILDCARD)` */ case class Match(selector: Tree, cases: List[CaseDef]) extends TermTree diff --git a/src/compiler/scala/reflect/internal/AnnotationInfos.scala b/src/compiler/scala/reflect/internal/AnnotationInfos.scala index d49787d3df..7f78d3a470 100644 --- a/src/compiler/scala/reflect/internal/AnnotationInfos.scala +++ b/src/compiler/scala/reflect/internal/AnnotationInfos.scala @@ -13,16 +13,15 @@ trait AnnotationInfos extends api.AnnotationInfos { self: SymbolTable => /** Arguments to classfile annotations (which are written to * bytecode as java annotations) are either: - * <ul> - * <li>constants</li> - * <li>arrays of constants</li> - * <li>or nested classfile annotations</li> - * </ul> + * + * - constants + * - arrays of constants + * - or nested classfile annotations */ abstract class ClassfileAnnotArg - /** Represents a compile-time Constant (Boolean, Byte, Short, - * Char, Int, Long, Float, Double, String, java.lang.Class or + /** Represents a compile-time Constant (`Boolean`, `Byte`, `Short`, + * `Char`, `Int`, `Long`, `Float`, `Double`, `String`, `java.lang.Class` or * an instance of a Java enumeration value). */ case class LiteralAnnotArg(const: Constant) @@ -40,9 +39,12 @@ trait AnnotationInfos extends api.AnnotationInfos { self: SymbolTable => object ArrayAnnotArg extends ArrayAnnotArgExtractor - /** A specific annotation argument that encodes an array of bytes as an array of `Long`. The type of the argument - * declared in the annotation must be `String`. This specialised class is used to encode scala signatures for - * reasons of efficiency, both in term of class-file size and in term of compiler performance. */ + /** A specific annotation argument that encodes an array of bytes as an + * array of `Long`. The type of the argument declared in the annotation + * must be `String`. This specialised class is used to encode Scala + * signatures for reasons of efficiency, both in term of class-file size + * and in term of compiler performance. + */ case class ScalaSigBytes(bytes: Array[Byte]) extends ClassfileAnnotArg { override def toString = (bytes map { byte => (byte & 0xff).toHexString }).mkString("[ ", " ", " ]") lazy val encodedBytes = ByteCodecs.encode(bytes) @@ -66,30 +68,21 @@ trait AnnotationInfos extends api.AnnotationInfos { self: SymbolTable => class AnnotationInfoBase - /** <p> - * Typed information about an annotation. It can be attached to - * either a symbol or an annotated type. - * </p> - * <p> - * Annotations are written to the classfile as java annotations - * if <code>atp</code> conforms to <code>ClassfileAnnotation</code> - * (the classfile parser adds this interface to any Java annotation - * class). - * </p> - * <p> - * Annotations are pickled (written to scala symtab attribute - * in the classfile) if <code>atp</code> inherits form - * <code>StaticAnnotation</code>. - * </p> - * <p> - * <code>args</code> stores arguments to Scala annotations, - * represented as typed trees. Note that these trees are not - * transformed by any phases following the type-checker. - * </p> - * <p> - * <code>assocs</code> stores arguments to classfile annotations - * as name-value pairs. - * </p> + /** Typed information about an annotation. It can be attached to either + * a symbol or an annotated type. + * + * Annotations are written to the classfile as Java annotations + * if `atp` conforms to `ClassfileAnnotation` (the classfile parser adds + * this interface to any Java annotation class). + * + * Annotations are pickled (written to scala symtab attribute in the + * classfile) if `atp` inherits form `StaticAnnotation`. + * + * `args` stores arguments to Scala annotations, represented as typed + * trees. Note that these trees are not transformed by any phases + * following the type-checker. + * + * `assocs` stores arguments to classfile annotations as name-value pairs. */ case class AnnotationInfo(atp: Type, args: List[Tree], assocs: List[(Name, ClassfileAnnotArg)]) @@ -142,7 +135,7 @@ trait AnnotationInfos extends api.AnnotationInfos { self: SymbolTable => lazy val classfileAnnotArgManifest: ClassManifest[ClassfileAnnotArg] = reflect.ClassManifest.classType(classOf[ClassfileAnnotArg]) - /** Symbol annotations parsed in Namer (typeCompleter of + /** Symbol annotations parsed in `Namer` (typeCompleter of * definitions) have to be lazy (#1782) */ case class LazyAnnotationInfo(annot: () => AnnotationInfo) diff --git a/src/compiler/scala/tools/nsc/backend/WorklistAlgorithm.scala b/src/compiler/scala/tools/nsc/backend/WorklistAlgorithm.scala index 6a3ed2513e..d6fab2eb63 100644 --- a/src/compiler/scala/tools/nsc/backend/WorklistAlgorithm.scala +++ b/src/compiler/scala/tools/nsc/backend/WorklistAlgorithm.scala @@ -3,7 +3,6 @@ * @author Martin Odersky */ - package scala.tools.nsc package backend @@ -15,14 +14,13 @@ import scala.collection.{ mutable, immutable } * function is applied repeatedly to the first element in the * worklist, as long as the stack is not empty. * - * The client class should mix-in this class and initialize the - * worklist field and define the <code>processElement</code> method. - * Then call the <code>run</code> method providing a function that - * initializes the worklist. + * The client class should mix-in this class and initialize the worklist + * field and define the `processElement` method. Then call the `run` method + * providing a function that initializes the worklist. * * @author Martin Odersky * @version 1.0 - * @see <a href="icode/Linearizers.html" target="contentFrame">scala.tools.nsc.backend.icode.Linearizers</a> + * @see [[scala.tools.nsc.backend.icode.Linearizers]] */ trait WorklistAlgorithm { type Elem @@ -31,9 +29,9 @@ trait WorklistAlgorithm { val worklist: WList /** - * Run the iterative algorithm until the worklist - * remains empty. The initializer is run once before - * the loop starts and should initialize the worklist. + * Run the iterative algorithm until the worklist remains empty. + * The initializer is run once before the loop starts and should + * initialize the worklist. * * @param initWorklist ... */ diff --git a/src/compiler/scala/tools/nsc/backend/icode/analysis/TypeFlowAnalysis.scala b/src/compiler/scala/tools/nsc/backend/icode/analysis/TypeFlowAnalysis.scala index 9ec8364db7..3d556c04ab 100644 --- a/src/compiler/scala/tools/nsc/backend/icode/analysis/TypeFlowAnalysis.scala +++ b/src/compiler/scala/tools/nsc/backend/icode/analysis/TypeFlowAnalysis.scala @@ -3,13 +3,12 @@ * @author Martin Odersky */ - package scala.tools.nsc package backend.icode.analysis import scala.collection.{mutable, immutable} -/** A data-flow analysis on types, that works on <code>ICode</code>. +/** A data-flow analysis on types, that works on `ICode`. * * @author Iulian Dragos */ diff --git a/src/compiler/scala/tools/nsc/doc/DocFactory.scala b/src/compiler/scala/tools/nsc/doc/DocFactory.scala index 71ee6dfcb8..43363f7961 100644 --- a/src/compiler/scala/tools/nsc/doc/DocFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/DocFactory.scala @@ -1,4 +1,7 @@ -/* NSC -- new Scala compiler -- Copyright 2007-2011 LAMP/EPFL */ +/* NSC -- new Scala compiler + * Copyright 2007-2011 LAMP/EPFL + * @author David Bernard, Manohar Jonnalagedda + */ package scala.tools.nsc package doc @@ -9,18 +12,20 @@ import util.NoPosition import io.{ File, Directory } import DocParser.Parsed -/** A documentation processor controls the process of generating Scala documentation, which is as follows. +/** A documentation processor controls the process of generating Scala + * documentation, which is as follows. * - * * A simplified compiler instance (with only the front-end phases enabled) is created, and additional - * ''sourceless'' comments are registered. + * * A simplified compiler instance (with only the front-end phases enabled) + * * is created, and additional ''sourceless'' comments are registered. * * Documentable files are compiled, thereby filling the compiler's symbol table. * * A documentation model is extracted from the post-compilation symbol table. * * A generator is used to transform the model into the correct final format (HTML). * - * A processor contains a single compiler instantiated from the processor's `settings`. Each call to `document` - * uses the same compiler instance with the same symbol table. In particular, this implies that the scaladoc site - * obtained from a call to `run` will contain documentation about files compiled during previous calls to the same - * processor's `run` method. + * A processor contains a single compiler instantiated from the processor's + * `settings`. Each call to `document` uses the same compiler instance with + * the same symbol table. In particular, this implies that the scaladoc site + * obtained from a call to `run` will contain documentation about files compiled + * during previous calls to the same processor's `run` method. * * @param reporter The reporter to which both documentation and compilation errors will be reported. * @param settings The settings to be used by the documenter and compiler for generating documentation. @@ -41,9 +46,10 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor override def forScaladoc = true } - /** Creates a scaladoc site for all symbols defined in this call's `files`, as well as those defined in `files` of - * previous calls to the same processor. - * @param files The list of paths (relative to the compiler's source path, or absolute) of files to document. */ + /** Creates a scaladoc site for all symbols defined in this call's `files`, + * as well as those defined in `files` of previous calls to the same processor. + * @param files The list of paths (relative to the compiler's source path, + * or absolute) of files to document. */ def makeUniverse(files: List[String]): Option[Universe] = { assert(settings.docformat.value == "html") new compiler.Run() compile files @@ -97,7 +103,7 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor /** Generate document(s) for all `files` containing scaladoc documenataion. * @param files The list of paths (relative to the compiler's source path, or absolute) of files to document. */ - def document(files: List[String]): Unit = { + def document(files: List[String]) { def generate() = { import doclet._ val docletClass = Class.forName(settings.docgenerator.value) // default is html.Doclet @@ -120,6 +126,7 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor try generate() catch documentError } + private[doc] def docdbg(msg: String) { if (settings.Ydocdebug.value) println(msg) diff --git a/src/compiler/scala/tools/nsc/doc/DocParser.scala b/src/compiler/scala/tools/nsc/doc/DocParser.scala index 1e45079c48..2bd80f31da 100644 --- a/src/compiler/scala/tools/nsc/doc/DocParser.scala +++ b/src/compiler/scala/tools/nsc/doc/DocParser.scala @@ -12,8 +12,8 @@ import util._ import interactive.RangePositions import DocParser.Parsed -/** A very minimal global customized for extracting DocDefs. It stops - * right after parsing so it can read DocDefs from source code which would +/** A very minimal global customized for extracting `DocDefs`. It stops + * right after parsing so it can read `DocDefs` from source code which would * otherwise cause the compiler to go haywire. */ class DocParser(settings: nsc.Settings, reporter: Reporter) @@ -31,8 +31,8 @@ class DocParser(settings: nsc.Settings, reporter: Reporter) phasesSet += syntaxAnalyzer } - /** Returns a list of DocParser.Parseds, which hold the DocDefs found in the - * given code along with the surrounding trees. + /** Returns a list of `DocParser.Parseds`, which hold the DocDefs found + * in the given code along with the surrounding trees. */ def docDefs(code: String) = { def loop(enclosing: List[Tree], tree: Tree): List[Parsed] = tree match { @@ -54,7 +54,7 @@ class DocParser(settings: nsc.Settings, reporter: Reporter) } /** Since the DocParser's whole reason for existing involves trashing a - * global, it is designed to bottle up general Global#Tree types rather + * global, it is designed to bottle up general `Global#Tree` types rather * than path dependent ones. The recipient will have to deal. */ object DocParser { diff --git a/src/compiler/scala/tools/nsc/doc/Index.scala b/src/compiler/scala/tools/nsc/doc/Index.scala index ce44291ade..b0ca23fea6 100644 --- a/src/compiler/scala/tools/nsc/doc/Index.scala +++ b/src/compiler/scala/tools/nsc/doc/Index.scala @@ -1,3 +1,8 @@ +/* NSC -- new Scala compiler + * Copyright 2005-2011 LAMP/EPFL + * @author Martin Odersky + */ + package scala.tools.nsc.doc import scala.collection._ diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala index 292eca91e3..9615b506c5 100644 --- a/src/compiler/scala/tools/nsc/doc/Settings.scala +++ b/src/compiler/scala/tools/nsc/doc/Settings.scala @@ -47,6 +47,7 @@ class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) { "A directory containing sources which should be parsed, no more (e.g. AnyRef.scala)", "" ) + lazy val uncompilableFiles = docUncompilable.value match { case "" => Nil case path => io.Directory(path).deepFiles filter (_ hasExtension "scala") toList @@ -57,7 +58,7 @@ class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) { val docsourceurl = StringSetting ( "-doc-source-url", "url", - "A URL pattern used to build links to template sources; use variables, for example: €{TPL_NAME} ('Seq'), €{TPL_OWNER} ('scala.collection'), €{FILE_PATH} ('scala/collection/Seq')", + "A URL pattern used to build links to template sources; use variables, for example: ?{TPL_NAME} ('Seq'), ?{TPL_OWNER} ('scala.collection'), ?{FILE_PATH} ('scala/collection/Seq')", "" ) diff --git a/src/compiler/scala/tools/nsc/doc/Universe.scala b/src/compiler/scala/tools/nsc/doc/Universe.scala index 71b4a4a4b0..fe0ef71680 100644 --- a/src/compiler/scala/tools/nsc/doc/Universe.scala +++ b/src/compiler/scala/tools/nsc/doc/Universe.scala @@ -1,3 +1,8 @@ +/* NSC -- new Scala compiler + * Copyright 2005-2011 LAMP/EPFL + * @author Martin Odersky + */ + package scala.tools.nsc.doc /** diff --git a/src/compiler/scala/tools/nsc/doc/html/Doclet.scala b/src/compiler/scala/tools/nsc/doc/html/Doclet.scala index 035a6e3dfa..5b722b5dd1 100644 --- a/src/compiler/scala/tools/nsc/doc/html/Doclet.scala +++ b/src/compiler/scala/tools/nsc/doc/html/Doclet.scala @@ -1,13 +1,19 @@ +/* NSC -- new Scala compiler + * Copyright 2007-2011 LAMP/EPFL + * @author David Bernard, Manohar Jonnalagedda + */ + package scala.tools.nsc.doc package html import doclet._ -/** * The default doclet used by the scaladoc command line tool when no user-provided doclet is provided. */ +/** The default doclet used by the scaladoc command line tool + * when no user-provided doclet is provided. */ class Doclet extends Generator with Universer with Indexer { def generateImpl() { new html.HtmlFactory(universe, index).generate } -}
\ No newline at end of file +} diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala index 88cd589797..49e39b717f 100644 --- a/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/html/HtmlFactory.scala @@ -16,12 +16,15 @@ import scala.collection._ * @author David Bernard * @author Gilles Dubochet */ class HtmlFactory(val universe: doc.Universe, index: doc.Index) { - /** The character encoding to be used for generated Scaladoc sites. This value is currently always UTF-8. */ + + /** The character encoding to be used for generated Scaladoc sites. + * This value is currently always UTF-8. */ def encoding: String = "UTF-8" def siteRoot: JFile = new JFile(universe.settings.outdir.value) - /** Generates the Scaladoc site for a model into the site root. A scaladoc site is a set of HTML and related files + /** Generates the Scaladoc site for a model into the site root. + * A scaladoc site is a set of HTML and related files * that document a model extracted from a compiler run. * @param model The model to generate in the form of a sequence of packages. */ def generate() { @@ -106,15 +109,16 @@ class HtmlFactory(val universe: doc.Universe, index: doc.Index) { } } - def writeTemplates(writeForThis: HtmlPage => Unit): Unit = { + def writeTemplates(writeForThis: HtmlPage => Unit) { val written = mutable.HashSet.empty[DocTemplateEntity] - def writeTemplate(tpl: DocTemplateEntity): Unit = + def writeTemplate(tpl: DocTemplateEntity) { if (!(written contains tpl)) { writeForThis(new page.Template(tpl)) written += tpl tpl.templates map (writeTemplate(_)) } + } writeTemplate(universe.rootPackage) } diff --git a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala index cfa846b097..44a1728c05 100644 --- a/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala +++ b/src/compiler/scala/tools/nsc/doc/html/HtmlPage.scala @@ -29,7 +29,7 @@ abstract class HtmlPage extends Page { thisPage => /** The body of this page. */ def body: NodeSeq - def writeFor(site: HtmlFactory): Unit = { + def writeFor(site: HtmlFactory) { val doctype = DocType("html", PublicID("-//W3C//DTD XHTML 1.1//EN", "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"), Nil) val html = @@ -45,7 +45,7 @@ abstract class HtmlPage extends Page { thisPage => val w = Channels.newWriter(fos.getChannel, site.encoding) try { w.write("<?xml version='1.0' encoding='" + site.encoding + "'?>\n") - w.write( doctype.toString + "\n") + w.write(doctype.toString + "\n") w.write(xml.Xhtml.toXhtml(html)) } finally { @@ -73,7 +73,8 @@ abstract class HtmlPage extends Page { thisPage => case Title(in, 3) => <h5>{ inlineToHtml(in) }</h5> case Title(in, _) => <h6>{ inlineToHtml(in) }</h6> case Paragraph(in) => <p>{ inlineToHtml(in) }</p> - case Code(data) => <pre>{ xml.Text(data) }</pre> + case Code(data) => + <pre>{ SyntaxHigh(data) }</pre> //<pre>{ xml.Text(data) }</pre> case UnorderedList(items) => <ul>{ listItemsToHtml(items) }</ul> case OrderedList(items, listStyle) => @@ -105,7 +106,7 @@ abstract class HtmlPage extends Page { thisPage => case Subscript(in) => <sub>{ inlineToHtml(in) }</sub> case Link(raw, title) => <a href={ raw }>{ inlineToHtml(title) }</a> case EntityLink(entity) => templateToHtml(entity) - case Monospace(text) => <code>{ xml.Text(text) }</code> + case Monospace(in) => <code>{ inlineToHtml(in) }</code> case Text(text) => xml.Text(text) case Summary(in) => inlineToHtml(in) case HtmlTag(tag) => xml.Unparsed(tag) @@ -172,13 +173,14 @@ abstract class HtmlPage extends Page { thisPage => /** Returns the _big image name corresponding to the DocTemplate Entity (upper left icon) */ def docEntityKindToBigImage(ety: DocTemplateEntity) = - if (ety.isTrait && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None) "trait_to_object_big.png" - else if (ety.isTrait) "trait_big.png" - else if (ety.isClass && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None) "class_to_object_big.png" - else if (ety.isClass) "class_big.png" - else if (ety.isObject && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None && ety.companion.get.isClass) "object_to_class_big.png" - else if (ety.isObject && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None && ety.companion.get.isTrait) "object_to_trait_big.png" - else if (ety.isObject) "object_big.png" - else if (ety.isPackage) "package_big.png" - else "class_big.png" // FIXME: an entity *should* fall into one of the above categories, but AnyRef is somehow not + if (ety.isTrait && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None) "trait_to_object_big.png" + else if (ety.isTrait) "trait_big.png" + else if (ety.isClass && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None) "class_to_object_big.png" + else if (ety.isClass) "class_big.png" + else if (ety.isObject && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None && ety.companion.get.isClass) "object_to_class_big.png" + else if (ety.isObject && !ety.companion.isEmpty && ety.companion.get.visibility.isPublic && ety.companion.get.inSource != None && ety.companion.get.isTrait) "object_to_trait_big.png" + else if (ety.isObject) "object_big.png" + else if (ety.isPackage) "package_big.png" + else "class_big.png" // FIXME: an entity *should* fall into one of the above categories, but AnyRef is somehow not + } diff --git a/src/compiler/scala/tools/nsc/doc/html/Page.scala b/src/compiler/scala/tools/nsc/doc/html/Page.scala index f72b0a49eb..c5bf3e0e37 100644 --- a/src/compiler/scala/tools/nsc/doc/html/Page.scala +++ b/src/compiler/scala/tools/nsc/doc/html/Page.scala @@ -1,4 +1,10 @@ +/* NSC -- new Scala compiler + * Copyright 2007-2011 LAMP/EPFL + * @author David Bernard, Manohar Jonnalagedda + */ + package scala.tools.nsc.doc.html + import scala.tools.nsc.doc.model._ import java.io.{FileOutputStream, File} import scala.reflect.NameTransformer @@ -6,9 +12,10 @@ import scala.reflect.NameTransformer abstract class Page { thisPage => - /** The path of this page, relative to the API site. `path.tail` is a list of folder names leading to this page (from - * closest package to one-above-root package), `path.head` is the file name of this page. Note that `path` has a - * length of at least one. */ + /** The path of this page, relative to the API site. `path.tail` is a list + * of folder names leading to this page (from closest package to + * one-above-root package), `path.head` is the file name of this page. + * Note that `path` has a length of at least one. */ def path: List[String] def absoluteLinkTo(path: List[String]) = path.reverse.mkString("/") @@ -22,8 +29,8 @@ abstract class Page { new FileOutputStream(file.getPath) } - /** Writes this page as a file. The file's location is relative to the generator's site root, and the encoding is - * also defined by the generator. + /** Writes this page as a file. The file's location is relative to the + * generator's site root, and the encoding is also defined by the generator. * @param generator The generator that is writing this page. */ def writeFor(site: HtmlFactory): Unit diff --git a/src/compiler/scala/tools/nsc/doc/html/SyntaxHigh.scala b/src/compiler/scala/tools/nsc/doc/html/SyntaxHigh.scala new file mode 100644 index 0000000000..f19f449d2c --- /dev/null +++ b/src/compiler/scala/tools/nsc/doc/html/SyntaxHigh.scala @@ -0,0 +1,286 @@ +/* NSC -- new Scala compiler + * Copyright 2010-2011 LAMP/EPFL + * @author Stephane Micheloud + */ + +package scala.tools.nsc.doc.html + +import xml.NodeSeq + +/** Highlight the syntax of Scala code appearing in a `{{{` wiki block + * (see method `HtmlPage.blockToHtml`). + * + * @author Stephane Micheloud + * @version 1.0 + */ +private[html] object SyntaxHigh { + + /** Reserved words, sorted alphabetically + * (see [[scala.reflect.internal.StdNames]]) */ + val reserved = Array( + "abstract", "case", "catch", "class", "def", + "do", "else", "extends", "false", "final", "finally", + "for", "if", "implicit", "import", "lazy", "match", + "new", "null", "object", "override", "package", + "private", "protected", "return", "sealed", "super", + "this", "throw", "trait", "true", "try", "type", + "val", "var", "while", "with", "yield") + + /** Annotations, sorted alphabetically */ + val annotations = Array( + "BeanProperty", "SerialVersionUID", + "beanGetter", "beanSetter", "bridge", "cloneable", + "deprecated", "deprecatedName", + "elidable", "field", "getter", "inline", + "migration", "native", "noinline", "param", + "remote", "setter", "specialized", "strictfp", "switch", + "tailrec", "throws", "transient", + "unchecked", "uncheckedStable", "uncheckedVariance", + "varargs", "volatile") + + /** Standard library classes/objects, sorted alphabetically */ + val standards = Array ( + "Any", "AnyRef", "AnyVal", "App", "Application", "Array", + "Boolean", "Byte", "Char", "Class", "Console", "Double", + "Enumeration", "Float", "Function", "Int", + "List", "Long", "Manifest", "Map", + "None", "Nothing", "Null", "Object", "Option", + "Pair", "Predef", + "Seq", "Set", "Short", "Some", "String", "Symbol", + "Triple", "Unit") + + def apply(data: String): NodeSeq = { + val buf = data.getBytes + val out = new StringBuilder + + def compare(offset: Int, key: String): Int = { + var i = offset + var j = 0 + val l = key.length + while (i < buf.length && j < l) { + val bch = buf(i).toChar + val kch = key charAt j + if (bch < kch) return -1 + else if (bch > kch) return 1 + i += 1 + j += 1 + } + if (j < l) -1 + else if (i < buf.length && + ('A' <= buf(i) && buf(i) <= 'Z' || + 'a' <= buf(i) && buf(i) <= 'z' || + '0' <= buf(i) && buf(i) <= '9' || + buf(i) == '_')) 1 + else 0 + } + + def lookup(a: Array[String], i: Int): Int = { + var lo = 0 + var hi = a.length - 1 + while (lo <= hi) { + val m = (hi + lo) / 2 + val d = compare(i, a(m)) + if (d < 0) hi = m - 1 + else if (d > 0) lo = m + 1 + else return m + } + -1 + } + + def comment(i: Int): String = { + val out = new StringBuilder("/") + def line(i: Int): Int = + if (i == buf.length || buf(i) == '\n') i + else { + out append buf(i).toChar + line(i+1) + } + var level = 0 + def multiline(i: Int, star: Boolean): Int = { + if (i == buf.length) return i + val ch = buf(i).toChar + out append ch + ch match { + case '*' => + if (star) level += 1 + multiline(i+1, !star) + case '/' => + if (star) { + if (level > 0) level -= 1 + if (level == 0) i else multiline(i+1, true) + } else + multiline(i+1, false) + case _ => + multiline(i+1, false) + } + } + if (buf(i) == '/') line(i) else multiline(i, true) + out.toString + } + + /* e.g. `val endOfLine = '\u000A'`*/ + def charlit(j: Int): String = { + val out = new StringBuilder("'") + def charlit0(i: Int, bslash: Boolean): Int = { + if (i == buf.length) i + else if (i > j+6) { out setLength 0; j } + else { + val ch = buf(i).toChar + out append ch + ch match { + case '\\' => + charlit0(i+1, true) + case '\'' if !bslash => + i + case _ => + if (bslash && '0' <= ch && ch <= '9') charlit0(i+1, true) + else charlit0(i+1, false) + } + } + } + charlit0(j, false) + out.toString + } + + def strlit(i: Int): String = { + val out = new StringBuilder("\"") + def strlit0(i: Int, bslash: Boolean): Int = { + if (i == buf.length) return i + val ch = buf(i).toChar + out append ch + ch match { + case '\\' => + strlit0(i+1, true) + case '"' if !bslash => + i + case _ => + strlit0(i+1, false) + } + } + strlit0(i, false) + out.toString + } + + def numlit(i: Int): String = { + val out = new StringBuilder + def intg(i: Int): Int = { + if (i == buf.length) return i + val ch = buf(i).toChar + ch match { + case '.' => + out append ch + frac(i+1) + case _ => + if (Character.isDigit(ch)) { + out append ch + intg(i+1) + } else i + } + } + def frac(i: Int): Int = { + if (i == buf.length) return i + val ch = buf(i).toChar + ch match { + case 'e' | 'E' => + out append ch + expo(i+1, false) + case _ => + if (Character.isDigit(ch)) { + out append ch + frac(i+1) + } else i + } + } + def expo(i: Int, signed: Boolean): Int = { + if (i == buf.length) return i + val ch = buf(i).toChar + ch match { + case '+' | '-' if !signed => + out append ch + expo(i+1, true) + case _ => + if (Character.isDigit(ch)) { + out append ch + expo(i+1, signed) + } else i + } + } + intg(i) + out.toString + } + + def parse(pre: String, i: Int): Int = { + out append pre + if (i == buf.length) return i + buf(i) match { + case '\n' => + parse("\n", i+1) + case ' ' => + parse(" ", i+1) + case '&' => + parse("&", i+1) + case '<' => + val ch = buf(i+1).toChar + if (ch == '-' || ch == ':' || ch == '%') + parse("<span class=\"kw\"><"+ch+"</span>", i+2) + else + parse("<", i+1) + case '>' => + if (buf(i+1) == ':') + parse("<span class=\"kw\">>:</span>", i+2) + else + parse(">", i+1) + case '=' => + if (buf(i+1) == '>') + parse("<span class=\"kw\">=></span>", i+2) + else + parse(buf(i).toChar.toString, i+1) + case '/' => + if (buf(i+1) == '/' || buf(i+1) == '*') { + val c = comment(i+1) + parse("<span class=\"cmt\">"+c+"</span>", i+c.length) + } else + parse(buf(i).toChar.toString, i+1) + case '\'' => + val s = charlit(i+1) + if (s.length > 0) + parse("<span class=\"lit\">"+s+"</span>", i+s.length) + else + parse(buf(i).toChar.toString, i+1) + case '"' => + val s = strlit(i+1) + parse("<span class=\"lit\">"+s+"</span>", i+s.length) + case '@' => + val k = lookup(annotations, i+1) + if (k >= 0) + parse("<span class=\"ano\">@"+annotations(k)+"</span>", i+annotations(k).length+1) + else + parse(buf(i).toChar.toString, i+1) + case _ => + if (i == 0 || !Character.isJavaIdentifierPart(buf(i-1).toChar)) { + if (Character.isDigit(buf(i)) || + (buf(i) == '.' && Character.isDigit(buf(i+1)))) { + val s = numlit(i) + parse("<span class=\"num\">"+s+"</span>", i+s.length) + } else { + val k = lookup(reserved, i) + if (k >= 0) + parse("<span class=\"kw\">"+reserved(k)+"</span>", i+reserved(k).length) + else { + val k = lookup(standards, i) + if (k >= 0) + parse("<span class=\"std\">"+standards(k)+"</span>", i+standards(k).length) + else + parse(buf(i).toChar.toString, i+1) + } + } + } else + parse(buf(i).toChar.toString, i+1) + } + i + } + + parse("", 0) + xml.Unparsed(out.toString) + } +} diff --git a/src/compiler/scala/tools/nsc/doc/html/page/Index.scala b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala index 7203230084..346780147e 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Index.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala @@ -109,6 +109,7 @@ class Index(universe: doc.Universe, index: doc.Index) extends HtmlPage { </div> def packageQualifiedName(ety: DocTemplateEntity): String = - if (ety.inTemplate.isPackage) ety.name else (packageQualifiedName(ety.inTemplate) + "." + ety.name) + if (ety.inTemplate.isPackage) ety.name + else (packageQualifiedName(ety.inTemplate) + "." + ety.name) } diff --git a/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala b/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala index 2cafe6caa3..7edd4937c4 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala @@ -1,4 +1,10 @@ +/* NSC -- new Scala compiler + * Copyright 2007-2011 LAMP/EPFL + * @author David Bernard, Manohar Jonnalagedda + */ + package scala.tools.nsc.doc.html.page + import scala.tools.nsc.doc import scala.tools.nsc.doc.model.{Package, DocTemplateEntity} import scala.tools.nsc.doc.html.{Page, HtmlFactory} @@ -8,7 +14,7 @@ import scala.util.parsing.json.{JSONObject, JSONArray} class IndexScript(universe: doc.Universe, index: doc.Index) extends Page { def path = List("index.js") - override def writeFor(site: HtmlFactory): Unit = { + override def writeFor(site: HtmlFactory) { val stream = createFileOutputStream(site) val writer = Channels.newWriter(stream.getChannel, site.encoding) try { diff --git a/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala b/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala index 3e57f260c3..a76cc231b4 100755 --- a/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala @@ -11,7 +11,7 @@ import doc.model._ class ReferenceIndex(letter: Char, index: doc.Index, universe: Universe) extends HtmlPage { - def path = List("index-"+letter+".html","index") + def path = List("index-"+letter+".html", "index") def title = { val s = universe.settings diff --git a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala index 61a445e2a3..ccc40013f1 100644 --- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala +++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala @@ -45,9 +45,9 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage { case _ => Nil }) - /* for body, there is a special case for AnyRef, otherwise AnyRef appears like a package/object - * this problem should be fixed, this implementation is just a patch - */ + /* for body, there is a special case for AnyRef, otherwise AnyRef appears + * like a package/object this problem should be fixed, this implementation + * is just a patch. */ val body = { val templateName = if (tpl.isRootPackage) "root package" else tpl.name val displayName = tpl.companion match { @@ -63,7 +63,8 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage { <p id="owner">{ templatesToHtml(tpl.inTemplate.toRoot.reverse.tail, xml.Text(".")) }</p> } - <body class={ if (tpl.isTrait || tpl.isClass || tpl.qualifiedName == "scala.AnyRef") "type" else "value" }> + <body class={ if (tpl.isTrait || tpl.isClass || tpl.qualifiedName == "scala.AnyRef") "type" else "value" } + onload={ "sh_highlightDocument('../lib/', '.min.js');" }> <div id="definition"> { tpl.companion match { @@ -339,7 +340,7 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage { val annotationsWithHiddenArguments = List("deprecated", "Deprecated", "migration") def showArguments(annotation: Annotation) = - if (annotationsWithHiddenArguments.contains(annotation.qualifiedName)) false else true + !(annotationsWithHiddenArguments.contains(annotation.qualifiedName)) if (!mbr.annotations.isEmpty) { <dt>Annotations</dt> @@ -522,7 +523,13 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage { <span class="kind">{ kindToString(mbr) }</span> <span class="symbol"> { - val nameHtml = <span class={"name" + (if (mbr.deprecation.isDefined) " deprecated" else "") }>{ if (mbr.isConstructor) tpl.name else mbr.name }</span> + val nameHtml = { + val value = if (mbr.isConstructor) tpl.name else mbr.name + if (mbr.deprecation.isDefined) + <span class={"name deprecated"} title={"Deprecated: "+bodyToStr(mbr.deprecation.get)}>{ value }</span> + else + <span class={"name"}>{ value }</span> + } if (!nameLink.isEmpty) <a href={nameLink}>{nameHtml}</a> else nameHtml @@ -616,7 +623,7 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage { def codeStringToXml(text: String): NodeSeq = { var goodLookingXml: NodeSeq = NodeSeq.Empty var indent = 0 - for(c<-text) c match { + for (c <- text) c match { case '{' => indent+=1 goodLookingXml ++= Text("{") case '}' => indent-=1 @@ -637,7 +644,7 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage { val str = tree.expression val length = str.length var myXml: NodeSeq = NodeSeq.Empty - for( (from, (member, to)) <- tree.refEntity.toSeq) { + for ((from, (member, to)) <- tree.refEntity.toSeq) { if (index < from) { myXml ++= codeStringToXml(str.substring(index,from)) index = from @@ -664,13 +671,13 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage { if (index <= length-1) myXml ++= codeStringToXml(str.substring(index, length )) - if(length < 36) + if (length < 36) <span class="symbol">{ myXml }</span> else <span class="defval" name={ myXml }>{ "..." }</span> } - def argumentsToHtml(argss: List[ValueArgument]): NodeSeq = { + private def argumentsToHtml(argss: List[ValueArgument]): NodeSeq = { def argumentsToHtml0(argss: List[ValueArgument]): NodeSeq = argss match { case Nil => NodeSeq.Empty case arg :: Nil => argumentToHtml(arg) @@ -679,7 +686,7 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage { <span class="args">({ argumentsToHtml0(argss) })</span> } - def argumentToHtml(arg: ValueArgument): NodeSeq = { + private def argumentToHtml(arg: ValueArgument): NodeSeq = { <span> { arg.parameter match { @@ -691,4 +698,23 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage { </span> } + private def bodyToStr(body: comment.Body): String = + body.blocks flatMap (blockToStr(_)) mkString "" + + private def blockToStr(block: comment.Block): String = block match { + case comment.Paragraph(in) => inlineToStr(in) + case _ => block.toString + } + + private def inlineToStr(inl: comment.Inline): String = inl match { + case comment.Chain(items) => items flatMap (inlineToStr(_)) mkString "" + case comment.Italic(in) => inlineToStr(in) + case comment.Bold(in) => inlineToStr(in) + case comment.Underline(in) => inlineToStr(in) + case comment.Monospace(in) => inlineToStr(in) + case comment.Text(text) => text + case comment.Summary(in) => inlineToStr(in) + case _ => inl.toString + } + } diff --git a/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css b/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css index 87e9972812..771fa8f550 100644 --- a/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css +++ b/src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css @@ -398,6 +398,30 @@ div.members > ol > li:last-child { font-family: monospace; } +.cmt pre span.ano { + color: blue; +} + +.cmt pre span.cmt { + color: green; +} + +.cmt pre span.kw { + font-weight: bold; +} + +.cmt pre span.lit { + color: #c71585; +} + +.cmt pre span.num { + color: #1e90ff; /* dodgerblue */ +} + +.cmt pre span.std { + color: #008080; /* teal */ +} + .cmt ul { display: block; list-style: circle; diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala b/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala index 52ef154325..ef4047cebf 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/Body.scala @@ -1,4 +1,7 @@ -/* NSC -- new Scala compiler -- Copyright 2007-2011 LAMP/EPFL */ +/* NSC -- new Scala compiler + * Copyright 2007-2011 LAMP/EPFL + * @author Manohar Jonnalagedda + */ package scala.tools.nsc package doc @@ -9,8 +12,9 @@ import scala.collection._ import java.net.URL -/** A body of text. A comment has a single body, which is composed of at least one block. Inside every body is exactly - * one summary (see [[scala.tools.nsc.doc.model.comment.Summary]]). */ +/** A body of text. A comment has a single body, which is composed of + * at least one block. Inside every body is exactly one summary (see + * [[scala.tools.nsc.doc.model.comment.Summary]]). */ final case class Body(blocks: Seq[Block]) { /** The summary text of the comment body. */ @@ -18,14 +22,14 @@ final case class Body(blocks: Seq[Block]) { def summaryInBlock(block: Block): Seq[Inline] = block match { case Title(text, _) => summaryInInline(text) case Paragraph(text) => summaryInInline(text) - case UnorderedList(items) => items flatMap { summaryInBlock(_) } - case OrderedList(items, _) => items flatMap { summaryInBlock(_) } - case DefinitionList(items) => items.values.toSeq flatMap { summaryInBlock(_) } + case UnorderedList(items) => items flatMap summaryInBlock + case OrderedList(items, _) => items flatMap summaryInBlock + case DefinitionList(items) => items.values.toSeq flatMap summaryInBlock case _ => Nil } def summaryInInline(text: Inline): Seq[Inline] = text match { case Summary(text) => List(text) - case Chain(items) => items flatMap { summaryInInline(_) } + case Chain(items) => items flatMap summaryInInline case Italic(text) => summaryInInline(text) case Bold(text) => summaryInInline(text) case Underline(text) => summaryInInline(text) @@ -65,7 +69,7 @@ final case class Superscript(text: Inline) extends Inline final case class Subscript(text: Inline) extends Inline final case class Link(target: String, title: Inline) extends Inline final case class EntityLink(target: TemplateEntity) extends Inline -final case class Monospace(text: String) extends Inline +final case class Monospace(text: Inline) extends Inline final case class Text(text: String) extends Inline final case class HtmlTag(data: String) extends Inline { def canClose(open: HtmlTag) = { diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/Comment.scala b/src/compiler/scala/tools/nsc/doc/model/comment/Comment.scala index b3033188e9..914275dd8d 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/Comment.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/Comment.scala @@ -1,4 +1,7 @@ -/* NSC -- new Scala compiler -- Copyright 2007-2011 LAMP/EPFL */ +/* NSC -- new Scala compiler + * Copyright 2007-2011 LAMP/EPFL + * @author Manohar Jonnalagedda + */ package scala.tools.nsc package doc @@ -11,8 +14,8 @@ import scala.collection._ * * '''Note:''' the only instantiation site of this class is in [[CommentFactory]]. * - * @author Gilles Dubochet - * @author Manohar Jonnalagedda */ + * @author Manohar Jonnalagedda + * @author Gilles Dubochet */ abstract class Comment { /** The main body of the comment that describes what the entity does and is. */ @@ -20,10 +23,10 @@ abstract class Comment { private def closeHtmlTags(inline: Inline) = { val stack = mutable.ListBuffer.empty[HtmlTag] - def scan(i: Inline): Unit = { + def scan(i: Inline) { i match { case Chain(list) => - list.foreach(scan) + list foreach scan case tag: HtmlTag => { if (stack.length > 0 && tag.canClose(stack.last)) { stack.remove(stack.length-1) @@ -57,26 +60,30 @@ abstract class Comment { /** A list of authors. The empty list is used when no author is defined. */ def authors: List[Body] - /** A list of other resources to see, including links to other entities or to external documentation. The empty list - * is used when no other resource is mentionned. */ + /** A list of other resources to see, including links to other entities or + * to external documentation. The empty list is used when no other resource + * is mentionned. */ def see: List[Body] - /** A description of the result of the entity. Typically, this provides additional information on the domain of the - * result, contractual post-conditions, etc. */ + /** A description of the result of the entity. Typically, this provides additional + * information on the domain of the result, contractual post-conditions, etc. */ def result: Option[Body] - /** A map of exceptions that the entity can throw when accessed, and a description of what they mean. */ + /** A map of exceptions that the entity can throw when accessed, and a + * description of what they mean. */ def throws: Map[String, Body] - /** A map of value parameters, and a description of what they are. Typically, this provides additional information on - * the domain of the parameters, contractual pre-conditions, etc. */ + /** A map of value parameters, and a description of what they are. Typically, + * this provides additional information on the domain of the parameters, + * contractual pre-conditions, etc. */ def valueParams: Map[String, Body] - /** A map of type parameters, and a description of what they are. Typically, this provides additional information on - * the domain of the parameters. */ + /** A map of type parameters, and a description of what they are. Typically, + * this provides additional information on the domain of the parameters. */ def typeParams: Map[String, Body] - /** The version number of the entity. There is no formatting or further meaning attached to this value. */ + /** The version number of the entity. There is no formatting or further + * meaning attached to this value. */ def version: Option[Body] /** A version number of a containing entity where this member-entity was introduced. */ @@ -85,8 +92,8 @@ abstract class Comment { /** An annotation as to expected changes on this entity. */ def todo: List[Body] - /** Whether the entity is deprecated. Using the "@deprecated" Scala attribute is prefereable to using this Scaladoc - * tag. */ + /** Whether the entity is deprecated. Using the `@deprecated` Scala attribute + * is prefereable to using this Scaladoc tag. */ def deprecated: Option[Body] /** An additional note concerning the contract of the entity. */ diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala index e332b28c67..ea36eb03c7 100644 --- a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala +++ b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala @@ -1,4 +1,7 @@ -/* NSC -- new Scala compiler -- Copyright 2007-2011 LAMP/EPFL */ +/* NSC -- new Scala compiler + * Copyright 2007-2011 LAMP/EPFL + * @author Manohar Jonnalagedda + */ package scala.tools.nsc package doc @@ -11,8 +14,9 @@ import scala.util.matching.Regex import scala.annotation.switch import util.{NoPosition, Position} -/** The comment parser transforms raw comment strings into `Comment` objects. Call `parse` to run the parser. Note that - * the parser is stateless and should only be built once for a given Scaladoc run. +/** The comment parser transforms raw comment strings into `Comment` objects. + * Call `parse` to run the parser. Note that the parser is stateless and + * should only be built once for a given Scaladoc run. * * @param reporter The reporter on which user messages (error, warnings) should be printed. * @@ -41,8 +45,9 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => } } - /** A comment is usualy created by the parser, however for some special cases we have to give - * some inTpl comments (parent class for example) to the comment of the symbol + /** A comment is usualy created by the parser, however for some special + * cases we have to give some `inTpl` comments (parent class for example) + * to the comment of the symbol. * This function manages some of those cases : Param accessor and Primary constructor */ def defineComment(sym: global.Symbol, inTpl: => DocTemplateImpl):Option[Comment] = { @@ -131,15 +136,18 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => protected def oops(msg: String): Nothing = throw FatalError("program logic: " + msg) - /** The body of a line, dropping the (optional) start star-marker, one leading whitespace and all trailing whitespace. */ + /** The body of a line, dropping the (optional) start star-marker, + * one leading whitespace and all trailing whitespace. */ protected val CleanCommentLine = new Regex("""(?:\s*\*\s?)?(.*)""") - /** Dangerous HTML tags that should be replaced by something safer, such as wiki syntax, or that should be dropped. */ + /** Dangerous HTML tags that should be replaced by something safer, + * such as wiki syntax, or that should be dropped. */ protected val DangerousTags = new Regex("""<(/?(div|ol|ul|li|h[1-6]|p))( [^>]*)?/?>|<!--.*-->""") - /** Maps a dangerous HTML tag to a safe wiki replacement, or an empty string if it cannot be salvaged. */ + /** Maps a dangerous HTML tag to a safe wiki replacement, or an empty string + * if it cannot be salvaged. */ protected def htmlReplacement(mtch: Regex.Match): String = mtch.group(1) match { case "p" | "div" => "\n\n" case "h1" => "\n= " @@ -154,7 +162,8 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => case _ => "" } - /** Javadoc tags that should be replaced by something useful, such as wiki syntax, or that should be dropped. */ + /** Javadoc tags that should be replaced by something useful, such as wiki + * syntax, or that should be dropped. */ protected val JavadocTags = new Regex("""\{\@(code|docRoot|inheritDoc|link|linkplain|literal|value)([^}]*)\}""") @@ -180,8 +189,8 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => protected val SimpleTag = new Regex("""\s*@(\S+)\s+(.*)""") - /** A Scaladoc tag linked to a symbol. Returns the name of the tag, the name of the symbol, and the rest of the - * line. */ + /** A Scaladoc tag linked to a symbol. Returns the name of the tag, the name + * of the symbol, and the rest of the line. */ protected val SymbolTag = new Regex("""\s*@(param|tparam|throws)\s+(\S*)\s*(.*)""") @@ -193,7 +202,8 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => protected val CodeBlockEnd = new Regex("""(.*)((?:\}\}\})|(?:\u000E</pre>\u000E))(.*)""") - /** A key used for a tag map. The key is built from the name of the tag and from the linked symbol if the tag has one. + /** A key used for a tag map. The key is built from the name of the tag and + * from the linked symbol if the tag has one. * Equality on tag keys is structural. */ protected sealed abstract class TagKey { def name: String @@ -208,8 +218,8 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => * @param pos The position of the comment in source. */ protected def parse(comment: String, src: String, pos: Position): Comment = { - /** The cleaned raw comment as a list of lines. Cleaning removes comment start and end markers, line start markers - * and unnecessary whitespace. */ + /** The cleaned raw comment as a list of lines. Cleaning removes comment + * start and end markers, line start markers and unnecessary whitespace. */ def clean(comment: String): List[String] = { def cleanLine(line: String): String = { //replaceAll removes trailing whitespaces @@ -228,9 +238,10 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => markedTagComment.lines.toList map (cleanLine(_)) } - /** Parses a comment (in the form of a list of lines) to a Comment instance, recursively on lines. To do so, it - * splits the whole comment into main body and tag bodies, then runs the `WikiParser` on each body before creating - * the comment instance. + /** Parses a comment (in the form of a list of lines) to a `Comment` + * instance, recursively on lines. To do so, it splits the whole comment + * into main body and tag bodies, then runs the `WikiParser` on each body + * before creating the comment instance. * * @param docBody The body of the comment parsed until now. * @param tags All tags parsed until now. @@ -367,7 +378,8 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => } - /** Parses a string containing wiki syntax into a `Comment` object. Note that the string is assumed to be clean: + /** Parses a string containing wiki syntax into a `Comment` object. + * Note that the string is assumed to be clean: * - Removed Scaladoc start and end markers. * - Removed start-of-line star and one whitespace afterwards (if present). * - Removed all end-of-line whitespace. @@ -388,7 +400,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => def document(): Body = { nextChar() val blocks = new mutable.ListBuffer[Block] - while(char != endOfText) + while (char != endOfText) blocks += block() Body(blocks.toList) } @@ -429,10 +441,11 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => * nListBlock ::= nLine { mListBlock } * nLine ::= nSpc listStyle para '\n' * }}} - * Where n and m stand for the number of spaces. When m > n, a new list is nested. */ + * Where n and m stand for the number of spaces. When `m > n`, a new list is nested. */ def listBlock: Block = { - /** Consumes one list item block and returns it, or None if the block is not a list or a different list. */ + /** Consumes one list item block and returns it, or None if the block is + * not a list or a different list. */ def listLine(indent: Int, style: String): Option[Block] = if (countWhitespace > indent && checkList) Some(listBlock) @@ -446,7 +459,8 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => Some(p) } - /** Consumes all list item blocks (possibly with nested lists) of the same list and returns the list block. */ + /** Consumes all list item blocks (possibly with nested lists) of the + * same list and returns the list block. */ def listLevel(indent: Int, style: String): Block = { val lines = mutable.ListBuffer.empty[Block] var line: Option[Block] = listLine(indent, style) @@ -461,7 +475,6 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => val indent = countWhitespace val style = (listStyles.keys find { checkSkipInitWhitespace(_) }).getOrElse(listStyles.keys.head) listLevel(indent, style) - } def code(): Block = { @@ -548,10 +561,11 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => } case _ => ; } - } while (stack.length > 0 && char != endOfText); + } while (stack.length > 0 && char != endOfText) - return list.mkString("") + list mkString "" } + def inline(isInlineEnd: => Boolean): Inline = { def inline0(): Inline = { @@ -575,7 +589,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => val inlines: List[Inline] = { val iss = mutable.ListBuffer.empty[Inline] iss += inline0() - while(!isInlineEnd && !checkParaEnded) { + while (!isInlineEnd && !checkParaEnded) { val skipEndOfLine = if (char == endOfLine) { nextChar() true @@ -627,9 +641,9 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => def monospace(): Inline = { jump("`") - readUntil { char == '`' } + val i = inline(check("`")) jump("`") - Monospace(getRead()) + Monospace(i) } def underline(): Inline = { @@ -732,9 +746,9 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => }) } - def reportError(pos: Position, message: String): Unit = + def reportError(pos: Position, message: String) { reporter.warning(pos, message) - + } } protected sealed class CharReader(buffer: Array[Char]) { reader => @@ -742,7 +756,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => var char: Char = _ var offset: Int = 0 - final def nextChar(): Unit = { + final def nextChar() { if (offset >= buffer.length) char = endOfText else { @@ -857,9 +871,9 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => final def jumpUntil(ch: Char): Int = { var count = 0 - while(char != ch && char != endOfText) { + while (char != ch && char != endOfText) { nextChar() - count=count+1 + count += 1 } count } @@ -868,7 +882,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => assert(chars.length > 0) var count = 0 val c = chars(0) - while(!check(chars) && char != endOfText) { + while (!check(chars) && char != endOfText) { nextChar() while (char != c && char != endOfText) { nextChar() @@ -901,7 +915,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => final def readUntil(ch: Char): Int = { var count = 0 - while(char != ch && char != endOfText) { + while (char != ch && char != endOfText) { readBuilder += char nextChar() } @@ -912,7 +926,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => assert(chars.length > 0) var count = 0 val c = chars(0) - while(!check(chars) && char != endOfText) { + while (!check(chars) && char != endOfText) { readBuilder += char nextChar() while (char != c && char != endOfText) { @@ -934,10 +948,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory => /* CHARS CLASSES */ - def isWhitespace(c: Char) = (c: @switch) match { - case ' ' | '\t' => true - case _ => false - } + def isWhitespace(c: Char) = c == ' ' || c == '\t' } diff --git a/src/compiler/scala/tools/nsc/settings/MutableSettings.scala b/src/compiler/scala/tools/nsc/settings/MutableSettings.scala index 6081b58525..d2a3cc6699 100644 --- a/src/compiler/scala/tools/nsc/settings/MutableSettings.scala +++ b/src/compiler/scala/tools/nsc/settings/MutableSettings.scala @@ -514,8 +514,8 @@ class MutableSettings(val errorFn: String => Unit) withHelpSyntax(name + ":<" + arg + ">") } - /** A setting represented by a string in a given set of <code>choices</code>, - * (<code>default</code> unless set). + /** A setting represented by a string in a given set of `choices`, + * (`default` unless set). */ class ChoiceSetting private[nsc]( name: String, @@ -549,7 +549,7 @@ class MutableSettings(val errorFn: String => Unit) /** A setting represented by a list of strings which should be prefixes of * phase names. This is not checked here, however. Alternatively the string - * "all" can be used to represent all phases. + * `"all"` can be used to represent all phases. * (the empty list, unless set) */ class PhasesSetting private[nsc]( diff --git a/src/compiler/scala/tools/nsc/typechecker/Implicits.scala b/src/compiler/scala/tools/nsc/typechecker/Implicits.scala index c0e78d716c..79a76c7f92 100644 --- a/src/compiler/scala/tools/nsc/typechecker/Implicits.scala +++ b/src/compiler/scala/tools/nsc/typechecker/Implicits.scala @@ -388,7 +388,7 @@ trait Implicits { * Detect infinite search trees for implicits. * * @param info The given implicit info describing the implicit definition - * @pre <code>info.tpe</code> does not contain an error + * @pre `info.tpe` does not contain an error */ private def typedImplicit(info: ImplicitInfo, ptChecked: Boolean): SearchResult = { printInference("[typedImplicit] " + info) |