From 483ac5340db262adb5efcf747a97dc9f25bc0208 Mon Sep 17 00:00:00 2001 From: Felix Mulder Date: Tue, 24 Jan 2017 18:26:15 +0100 Subject: Fix javadoc indentation style parsing --- compiler/src/dotty/tools/dotc/core/Phases.scala | 12 ++-- .../dotc/transform/IsInstanceOfEvaluator.scala | 52 +++++++------- .../src/dotty/tools/dottydoc/DocCompiler.scala | 22 +++--- doc-tool/src/dotty/tools/dottydoc/DocDriver.scala | 4 +- .../src/dotty/tools/dottydoc/DocFrontEnd.scala | 10 +-- .../dotty/tools/dottydoc/api/scala/Dottydoc.scala | 42 +++++------ .../dottydoc/model/comment/CommentCleaner.scala | 2 +- .../dottydoc/model/comment/CommentRegex.scala | 2 +- doc-tool/test/CommentCleanerTest.scala | 83 ++++++++++++++++++++++ project/Build.scala | 32 +++++---- 10 files changed, 176 insertions(+), 85 deletions(-) create mode 100644 doc-tool/test/CommentCleanerTest.scala diff --git a/compiler/src/dotty/tools/dotc/core/Phases.scala b/compiler/src/dotty/tools/dotc/core/Phases.scala index b066943dd..7bba88542 100644 --- a/compiler/src/dotty/tools/dotc/core/Phases.scala +++ b/compiler/src/dotty/tools/dotc/core/Phases.scala @@ -267,12 +267,12 @@ object Phases { trait Phase extends DotClass { /** A name given to the `Phase` that can be used to debug the compiler. For - * instance, it is possible to print trees after a given phase using: - * - * ```bash - * $ ./bin/dotc -Xprint: sourceFile.scala - * ``` - */ + * instance, it is possible to print trees after a given phase using: + * + * ```bash + * $ ./bin/dotc -Xprint: sourceFile.scala + * ``` + */ def phaseName: String /** List of names of phases that should precede this phase */ diff --git a/compiler/src/dotty/tools/dotc/transform/IsInstanceOfEvaluator.scala b/compiler/src/dotty/tools/dotc/transform/IsInstanceOfEvaluator.scala index e6b1f5aac..0c6ee7a18 100644 --- a/compiler/src/dotty/tools/dotc/transform/IsInstanceOfEvaluator.scala +++ b/compiler/src/dotty/tools/dotc/transform/IsInstanceOfEvaluator.scala @@ -8,27 +8,27 @@ import Contexts.Context, Types._, Constants._, Decorators._, Symbols._ import TypeUtils._, TypeErasure._, Flags._ /** Implements partial evaluation of `sc.isInstanceOf[Sel]` according to: - * - * | Sel\sc | trait | class | final class | - * | ----------: | :------------------------: | :------------------------: | :--------------: | - * | trait | ? | ? | statically known | - * | class | ? | false if classes unrelated | statically known | - * | final class | false if classes unrelated | false if classes unrelated | statically known | - * - * This is a generalized solution to raising an error on unreachable match - * cases and warnings on other statically known results of `isInstanceOf`. - * - * Steps taken: - * - * 1. `evalTypeApply` will establish the matrix and choose the appropriate - * handling for the case: - * - Sel/sc is a value class or scrutinee is `Any` - * - `handleStaticallyKnown` - * - `falseIfUnrelated` with `scrutinee <:< selector` - * - `handleFalseUnrelated` - * - leave as is (`happens`) - * 2. Rewrite according to steps taken in 1 - */ + * + * | Sel\sc | trait | class | final class | + * | ----------: | :------------------------: | :------------------------: | :--------------: | + * | trait | ? | ? | statically known | + * | class | ? | false if classes unrelated | statically known | + * | final class | false if classes unrelated | false if classes unrelated | statically known | + * + * This is a generalized solution to raising an error on unreachable match + * cases and warnings on other statically known results of `isInstanceOf`. + * + * Steps taken: + * + * 1. `evalTypeApply` will establish the matrix and choose the appropriate + * handling for the case: + * - Sel/sc is a value class or scrutinee is `Any` + * - `handleStaticallyKnown` + * - `falseIfUnrelated` with `scrutinee <:< selector` + * - `handleFalseUnrelated` + * - leave as is (`happens`) + * 2. Rewrite according to steps taken in 1 + */ class IsInstanceOfEvaluator extends MiniPhaseTransform { thisTransformer => import dotty.tools.dotc.ast.tpd._ @@ -37,15 +37,15 @@ class IsInstanceOfEvaluator extends MiniPhaseTransform { thisTransformer => val phaseName = "isInstanceOfEvaluator" /** Transforms a [TypeApply](dotty.tools.dotc.ast.Trees.TypeApply) in order to - * evaluate an `isInstanceOf` check according to the rules defined above. - */ + * evaluate an `isInstanceOf` check according to the rules defined above. + */ override def transformTypeApply(tree: TypeApply)(implicit ctx: Context, info: TransformerInfo): Tree = { val defn = ctx.definitions /** Handles the four cases of statically known `isInstanceOf`s and gives - * the correct warnings, or an error if statically known to be false in - * match - */ + * the correct warnings, or an error if statically known to be false in + * match + */ def handleStaticallyKnown(select: Select, scrutinee: Type, selector: Type, inMatch: Boolean, pos: Position): Tree = { val scrutineeSubSelector = scrutinee <:< selector if (!scrutineeSubSelector && inMatch) { diff --git a/doc-tool/src/dotty/tools/dottydoc/DocCompiler.scala b/doc-tool/src/dotty/tools/dottydoc/DocCompiler.scala index 081883597..708c26cc0 100644 --- a/doc-tool/src/dotty/tools/dottydoc/DocCompiler.scala +++ b/doc-tool/src/dotty/tools/dottydoc/DocCompiler.scala @@ -7,17 +7,17 @@ import dotc.core.Phases.Phase import dotc.Compiler /** Custom Compiler with phases for the documentation tool - * - * The idea here is to structure `dottydoc` around the new infrastructure. As - * such, dottydoc will itself be a compiler. It will, however, produce a format - * that can be used by other tools or web-browsers. - * - * Example: - * 1. Use the existing FrontEnd to typecheck the code being fed to dottydoc, - * wihtout discarding AnyVal interfaces - * 2. Create an AST that is serializable - * 3. Serialize to JS object - */ + * + * The idea here is to structure `dottydoc` around the new infrastructure. As + * such, dottydoc will itself be a compiler. It will, however, produce a format + * that can be used by other tools or web-browsers. + * + * Example: + * 1. Use the existing FrontEnd to typecheck the code being fed to dottydoc, + * wihtout discarding AnyVal interfaces + * 2. Create an AST that is serializable + * 3. Serialize to JS object + */ class DocCompiler extends Compiler { override def phases: List[List[Phase]] = List( List(new DocFrontEnd), diff --git a/doc-tool/src/dotty/tools/dottydoc/DocDriver.scala b/doc-tool/src/dotty/tools/dottydoc/DocDriver.scala index e5a2cc266..ba7edb4b6 100644 --- a/doc-tool/src/dotty/tools/dottydoc/DocDriver.scala +++ b/doc-tool/src/dotty/tools/dottydoc/DocDriver.scala @@ -12,8 +12,8 @@ import dotc.core.Comments.ContextDoc import staticsite.Site /** `DocDriver` implements the main entry point to the Dotty documentation - * tool. It's methods are used by the external scala and java APIs. - */ + * tool. It's methods are used by the external scala and java APIs. + */ class DocDriver extends Driver { import _root_.java.util.{ Map => JMap } import model.java._ diff --git a/doc-tool/src/dotty/tools/dottydoc/DocFrontEnd.scala b/doc-tool/src/dotty/tools/dottydoc/DocFrontEnd.scala index 30c5e3e87..606fd0fc6 100644 --- a/doc-tool/src/dotty/tools/dottydoc/DocFrontEnd.scala +++ b/doc-tool/src/dotty/tools/dottydoc/DocFrontEnd.scala @@ -6,11 +6,11 @@ import dotc.core.Contexts.Context import dotc.CompilationUnit /** `DocFrontEnd` uses the Dotty `FrontEnd` without discarding the AnyVal - * interfaces for Boolean, Int, Char, Long, Byte etc. - * - * It currently still throws away Java sources by overriding - * `discardAfterTyper`. - */ + * interfaces for Boolean, Int, Char, Long, Byte etc. + * + * It currently still throws away Java sources by overriding + * `discardAfterTyper`. + */ class DocFrontEnd extends FrontEnd { override protected def discardAfterTyper(unit: CompilationUnit)(implicit ctx: Context) = unit.isJava diff --git a/doc-tool/src/dotty/tools/dottydoc/api/scala/Dottydoc.scala b/doc-tool/src/dotty/tools/dottydoc/api/scala/Dottydoc.scala index 1d0891bc2..9d00b08a3 100644 --- a/doc-tool/src/dotty/tools/dottydoc/api/scala/Dottydoc.scala +++ b/doc-tool/src/dotty/tools/dottydoc/api/scala/Dottydoc.scala @@ -7,27 +7,27 @@ import scala.collection.Map import java.net.URL /** The Dottydoc API is fairly simple. The tool creates an index by calling: - * `createIndex` with the same argument list as you would the compiler - e.g: - * - * ```scala - * val array: Array[String] = Array( - * "-language:Scala2" - * ) - * - * val index: Map[String, Package] = createIndex(array) - * ``` - * - * Once the index has been generated, the tool can also build a documentation - * API given a Mustache template and a flat resources structure (i.e. absolute - * paths to each resource, which will be put in the same directory). - * - * ```scala - * buildDocs("path/to/output/dir", templateURL, resources, index) - * ``` - * - * The tool can also generate JSON from the created index using `indexToJson` - * or directly using `createJsonIndex` - */ + * `createIndex` with the same argument list as you would the compiler - e.g: + * + * ```scala + * val array: Array[String] = Array( + * "-language:Scala2" + * ) + * + * val index: Map[String, Package] = createIndex(array) + * ``` + * + * Once the index has been generated, the tool can also build a documentation + * API given a Mustache template and a flat resources structure (i.e. absolute + * paths to each resource, which will be put in the same directory). + * + * ```scala + * buildDocs("path/to/output/dir", templateURL, resources, index) + * ``` + * + * The tool can also generate JSON from the created index using `indexToJson` + * or directly using `createJsonIndex` + */ trait Dottydoc extends DocDriver { /** Creates index from compiler arguments */ def createIndex(args: Array[String]): Map[String, Package] = diff --git a/doc-tool/src/dotty/tools/dottydoc/model/comment/CommentCleaner.scala b/doc-tool/src/dotty/tools/dottydoc/model/comment/CommentCleaner.scala index 27b0ff977..30b3b0de0 100644 --- a/doc-tool/src/dotty/tools/dottydoc/model/comment/CommentCleaner.scala +++ b/doc-tool/src/dotty/tools/dottydoc/model/comment/CommentCleaner.scala @@ -20,6 +20,6 @@ trait CommentCleaner { SafeTags.replaceAllIn(javadoclessComment, { mtch => _root_.java.util.regex.Matcher.quoteReplacement(safeTagMarker + mtch.matched + safeTagMarker) }) - markedTagComment.lines.toList map (cleanLine(_)) + markedTagComment.lines.toList map (cleanLine) } } diff --git a/doc-tool/src/dotty/tools/dottydoc/model/comment/CommentRegex.scala b/doc-tool/src/dotty/tools/dottydoc/model/comment/CommentRegex.scala index 2d75b0c66..faefd19a7 100644 --- a/doc-tool/src/dotty/tools/dottydoc/model/comment/CommentRegex.scala +++ b/doc-tool/src/dotty/tools/dottydoc/model/comment/CommentRegex.scala @@ -11,7 +11,7 @@ object Regexes { * one leading whitespace and all trailing whitespace */ val CleanCommentLine = - new Regex("""(?:\s*\*\s?)?(.*)""") + new Regex("""(?:\s*\*\s?\s?)?(.*)""") /** Dangerous HTML tags that should be replaced by something safer, * such as wiki syntax, or that should be dropped diff --git a/doc-tool/test/CommentCleanerTest.scala b/doc-tool/test/CommentCleanerTest.scala new file mode 100644 index 000000000..5cf5614c4 --- /dev/null +++ b/doc-tool/test/CommentCleanerTest.scala @@ -0,0 +1,83 @@ +package dotty.tools +package dottydoc + +import org.junit.Test +import org.junit.Assert._ + +import model.comment.CommentCleaner + +class CommentCleanerTest extends CommentCleaner { + @Test def simpleOneliner = { + assertEquals(List("lol"), clean("/** lol */")) + } + + @Test def multiline = { + val docstring = clean { + """|/** First + | * Second + | */ + |""".stripMargin + } + + assertEquals(List("First", "Second", ""), docstring) + } + + @Test def multilineBad = { + val docstring = clean { + """|/** First + | * Second + | */ + |""".stripMargin + } + + assertEquals(List("First", " Second", ""), docstring) + } + + @Test def multilineWorse = { + val docstring = clean { + """|/** First + | * Second + | * Third + | */ + |""".stripMargin + } + + assertEquals(List("First", " Second", "Third", ""), docstring) + } + + @Test def multilineFirstNoSpace = { + val docstring = clean { + """|/**First + | * Second + | * Third + | */ + |""".stripMargin + } + + assertEquals(List("First", " Second", "Third", ""), docstring) + } + + @Test def multilineFirstTwoSpaces = { + val docstring = clean { + """|/** First + | * Second + | * Third + | */ + |""".stripMargin + } + + assertEquals(List("First", " Second", "Third", ""), docstring) + } + + @Test def multilineFirstThreeSpaces = { + val docstring = clean { + """|/** First + | * Second + | * Third + | */ + |""".stripMargin + } + + assertEquals(List(" First", " Second", "Third", ""), docstring) + } +} diff --git a/project/Build.scala b/project/Build.scala index d104544c5..a6505a12c 100644 --- a/project/Build.scala +++ b/project/Build.scala @@ -55,6 +55,12 @@ object DottyBuild extends Build { // Compiles the documentation and static site lazy val genDocs = inputKey[Unit]("run dottydoc to generate static documentation site") + /** Dottydoc deps */ + lazy val dottydocDeps = SettingKey[Seq[ModuleID]]( + "dottydocDeps", + "dottydoc dependencies, should be moved to a dottydoc sbt subproject eventually" + ) + override def settings: Seq[Setting[_]] = { super.settings ++ Seq( scalaVersion in Global := scalacVersion, @@ -180,26 +186,28 @@ object DottyBuild extends Build { //http://stackoverflow.com/questions/10472840/how-to-attach-sources-to-sbt-managed-dependencies-in-scala-ide#answer-11683728 com.typesafe.sbteclipse.plugin.EclipsePlugin.EclipseKeys.withSource := true, + dottydocDeps := Seq( + "com.vladsch.flexmark" % "flexmark" % "0.11.1", + "com.vladsch.flexmark" % "flexmark-ext-gfm-tasklist" % "0.11.1", + "com.vladsch.flexmark" % "flexmark-ext-gfm-tables" % "0.11.1", + "com.vladsch.flexmark" % "flexmark-ext-autolink" % "0.11.1", + "com.vladsch.flexmark" % "flexmark-ext-anchorlink" % "0.11.1", + "com.vladsch.flexmark" % "flexmark-ext-emoji" % "0.11.1", + "com.vladsch.flexmark" % "flexmark-ext-gfm-strikethrough" % "0.11.1", + "com.vladsch.flexmark" % "flexmark-ext-yaml-front-matter" % "0.11.1", + "com.fasterxml.jackson.dataformat" % "jackson-dataformat-yaml" % "2.8.6", + "nl.big-o" % "liqp" % "0.6.7" + ), + // get libraries onboard partestDeps := Seq(scalaCompiler, "org.scala-lang" % "scala-reflect" % scalacVersion, "org.scala-lang" % "scala-library" % scalacVersion % "test"), libraryDependencies ++= partestDeps.value, + libraryDependencies ++= dottydocDeps.value, libraryDependencies ++= Seq("org.scala-lang.modules" %% "scala-xml" % "1.0.1", "org.scala-lang.modules" %% "scala-partest" % "1.0.11" % "test", - dottyOrganization % "dottydoc-client" % "0.1.0", - "com.vladsch.flexmark" % "flexmark" % "0.11.1", - "com.vladsch.flexmark" % "flexmark-ext-gfm-tasklist" % "0.11.1", - "com.vladsch.flexmark" % "flexmark-ext-gfm-tables" % "0.11.1", - "com.vladsch.flexmark" % "flexmark-ext-autolink" % "0.11.1", - "com.vladsch.flexmark" % "flexmark-ext-anchorlink" % "0.11.1", - "com.vladsch.flexmark" % "flexmark-ext-emoji" % "0.11.1", - "com.vladsch.flexmark" % "flexmark-ext-gfm-strikethrough" % "0.11.1", - "com.vladsch.flexmark" % "flexmark-ext-yaml-front-matter" % "0.11.1", - "com.fasterxml.jackson.dataformat" % "jackson-dataformat-yaml" % "2.8.6", - "nl.big-o" % "liqp" % "0.6.7", "com.novocode" % "junit-interface" % "0.11" % "test", - "com.github.spullara.mustache.java" % "compiler" % "0.9.3", "com.typesafe.sbt" % "sbt-interface" % sbtVersion.value), // enable improved incremental compilation algorithm incOptions := incOptions.value.withNameHashing(true), -- cgit v1.2.3