diff options
25 files changed, 577 insertions, 189 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) diff --git a/test/scaladoc/scala/model/CommentFactoryTest.scala b/test/scaladoc/scala/model/CommentFactoryTest.scala index 9f60d2a1b7..69c314a64c 100644 --- a/test/scaladoc/scala/model/CommentFactoryTest.scala +++ b/test/scaladoc/scala/model/CommentFactoryTest.scala @@ -46,7 +46,7 @@ object Test extends Properties("CommentFactory") { ) property("parse") = parse( "/** One `two` three */", - Chain(List(Text("One "), Monospace("two"), Text(" three"))) + Chain(List(Text("One "), Monospace(Text("two")), Text(" three"))) ) property("parse") = parse( @@ -59,21 +59,21 @@ object Test extends Properties("CommentFactory") { """ /** One `two` * three */""", - Chain(List(Text("One "), Monospace("two"), Text("\n"), Text("three"))) + Chain(List(Text("One "), Monospace(Text("two")), Text("\n"), Text("three"))) ) property("parse") = parse( """ /** One `two` * three */""", - Chain(List(Text("One "), Monospace("two"), Text("\n"), Text(" three"))) + Chain(List(Text("One "), Monospace(Text("two")), Text("\n"), Text(" three"))) ) property("parse") = parse( """ /** One * `two` three */""", - Chain(List(Text("One"), Text("\n"), Monospace("two"), Text(" three"))) + Chain(List(Text("One"), Text("\n"), Monospace(Text("two")), Text(" three"))) ) property("Trac #4361 - ^...^") = parse( |