Merge pull request #1874 from dotty-staging/topic/dottydoc-markdown

[doctool] Add markdown support && Static site generation

Author: felixmulder

.drone.yml

@@ -6,6 +6,23 @@ pipeline:
       - ln -s /var/cache/drone/scala-scala scala-scala
       - ./scripts/update-scala-library
       - sbt -J-Xmx4096m -J-XX:ReservedCodeCacheSize=512m -J-XX:MaxMetaspaceSize=1024m -Ddotty.drone.mem=4096m -ivy /var/cache/drone/ivy2 "${TEST}"
+    when:
+      branch:
+        exclude: gh-pages
+
+  documentation:
+    image: lampepfl/dotty:latest
+    pull: true
+    commands:
+      - ./project/scripts/genDocs "${TEST}" $BOT_PASS
+    when:
+      branch: master
+
+  slack:
+    image: plugins/slack
+    channel: dotty
+    when:
+      branch: master
 
 matrix:
   TEST:

.drone.yml.sig

@@ -0,0 +1 @@
+eyJhbGciOiJIUzI1NiJ9.cGlwZWxpbmU6CiAgdGVzdDoKICAgIGltYWdlOiBsYW1wZXBmbC9kb3R0eTpsYXRlc3QKICAgIHB1bGw6IHRydWUKICAgIGNvbW1hbmRzOgogICAgICAtIGxuIC1zIC92YXIvY2FjaGUvZHJvbmUvc2NhbGEtc2NhbGEgc2NhbGEtc2NhbGEKICAgICAgLSAuL3NjcmlwdHMvdXBkYXRlLXNjYWxhLWxpYnJhcnkKICAgICAgLSBzYnQgLUotWG14NDA5Nm0gLUotWFg6UmVzZXJ2ZWRDb2RlQ2FjaGVTaXplPTUxMm0gLUotWFg6TWF4TWV0YXNwYWNlU2l6ZT0xMDI0bSAtRGRvdHR5LmRyb25lLm1lbT00MDk2bSAtaXZ5IC92YXIvY2FjaGUvZHJvbmUvaXZ5MiAiJHtURVNUfSIKICAgIHdoZW46CiAgICAgIGJyYW5jaDoKICAgICAgICBleGNsdWRlOiBnaC1wYWdlcwoKICBkb2N1bWVudGF0aW9uOgogICAgaW1hZ2U6IGxhbXBlcGZsL2RvdHR5OmxhdGVzdAogICAgcHVsbDogdHJ1ZQogICAgY29tbWFuZHM6CiAgICAgIC0gLi9wcm9qZWN0L3NjcmlwdHMvZ2VuRG9jcyAiJHtURVNUfSIgJEJPVF9QQVNTCiAgICB3aGVuOgogICAgICBicmFuY2g6IG1hc3RlcgoKICBzbGFjazoKICAgIGltYWdlOiBwbHVnaW5zL3NsYWNrCiAgICBjaGFubmVsOiBkb3R0eQogICAgd2hlbjoKICAgICAgYnJhbmNoOiBtYXN0ZXIKCm1hdHJpeDoKICBURVNUOgogICAgLSB0ZXN0CiAgICAtIDtwdWJsaXNoTG9jYWw7ZG90dHktYm9vdHN0cmFwcGVkL3Rlc3QKICAgIC0gcGFydGVzdC1vbmx5LW5vLWJvb3RzdHJhcCAtLXNob3ctZGlmZiAtLXZlcmJvc2UKICAgIC0gcGFydGVzdC1vbmx5IC0tc2hvdy1kaWZmIC0tdmVyYm9zZQo.l7I2yJ5gewe0ObfP09MyJ9iGlXaPffen5Sh3HjS2oKs

compiler/src/dotty/tools/backend/jvm/LabelDefs.scala

@@ -37,44 +37,47 @@ import StdNames.nme
 
 /**
  * Verifies that each Label DefDef has only a single address to jump back and
- * reorders them such that they are not nested and this address is a fall-through address for JVM
- *
- * ei such code
- *
+ * reorders them such that they are not nested and this address is a
+ * fall-through address for the JVM.
  *
+ * ```scala
  * <label> def foo(i: Int) = {
  *   <label> def bar = 0
  *   <label> def dough(i: Int) = if (i == 0) bar else foo(i-1)
  *   dough(i)
- *   }
+ * }
  *
  * foo(100)
+ * ```
  *
- * will get rewritten to
+ * will get rewritten to:
  *
- *                                                  \
+ * ```scala
  * <label> def foo(i: Int) = dough(i)
  * <label> def dough(i: Int) = if (i == 0) bar else foo(i-1)
  * <label> def bar = 2
  *   foo(100)
+ * ```
  *
- *   Proposed way to generate this pattern in backend is:
+ * Proposed way to generate this pattern in backend is:
  *
- *  foo(100)
- *  <jump foo>
- *  <label> def foo(i: Int) = dough(i)
- *  // <jump a>                           // unreachable
- *  <label> def dough(i: Int) = if (i == 0) bar else foo(i-1)
- *  // <jump a>                           // unreachable
- *  <label> def bar = 2
- *  // <jump a>                           // unreachable
- *  <asm point a>
+ * ```scala
+ * foo(100)
+ * <jump foo>
+ * <label> def foo(i: Int) = dough(i)
+ * // <jump a>                           // unreachable
+ * <label> def dough(i: Int) = if (i == 0) bar else foo(i-1)
+ * // <jump a>                           // unreachable
+ * <label> def bar = 2
+ * // <jump a>                           // unreachable
+ * <asm point a>
+ * ```
  *
- *    Unreachable jumps will be eliminated by local dead code analysis.
- *    After JVM is smart enough to remove next-line jumps
+ * Unreachable jumps will be eliminated by local dead code analysis.
+ * After JVM is smart enough to remove next-line jumps
  *
- * Note that Label DefDefs can be only nested in Block, otherwise no one would be able to call them
- * Other DefDefs are eliminated
+ * Note that Label DefDefs can be only nested in Block, otherwise no one would
+ * be able to call them Other DefDefs are eliminated
  */
 class LabelDefs extends MiniPhaseTransform {
   def phaseName: String = "labelDef"

compiler/src/dotty/tools/dotc/config/ScalaSettings.scala

@@ -101,6 +101,7 @@ class ScalaSettings extends Settings.SettingGroup {
   val XoldPatmat = BooleanSetting("-Xoldpatmat", "Use the pre-2.10 pattern matcher. Otherwise, the 'virtualizing' pattern matcher is used in 2.10.")
   val XnoPatmatAnalysis = BooleanSetting("-Xno-patmat-analysis", "Don't perform exhaustivity/unreachability analysis. Also, ignore @switch annotation.")
   val XfullLubs = BooleanSetting("-Xfull-lubs", "Retains pre 2.10 behavior of less aggressive truncation of least upper bounds.")
+  val wikiSyntax = BooleanSetting("-Xwiki-syntax", "Retains the Scala2 behavior of using Wiki Syntax in Scaladoc")
 
   /** -Y "Private" settings
    */
@@ -212,11 +213,18 @@ class ScalaSettings extends Settings.SettingGroup {
     "A directory containing static resources needed for the API documentation"
   )
 
-  val DocTitle = StringSetting (
-    "-Ydoc-title",
-    "title",
-    "The overall name of the Scaladoc site",
-    ""
+  val siteRoot = StringSetting(
+    "-siteroot",
+    "site root",
+    "A directory containing static files from which to generate documentation",
+    sys.props("user.dir")
+  )
+
+  val projectName = StringSetting (
+    "-project",
+    "project title",
+    "The name of the project",
+    sys.props("user.dir").split(sys.props("file.separator")).last
   )
 
   val DocVersion = StringSetting (

compiler/src/dotty/tools/dotc/core/Phases.scala

@@ -263,6 +263,13 @@ 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:<phaseNameHere> sourceFile.scala
+     *  ```
+     */
     def phaseName: String
 
     /** List of names of phases that should precede this phase */

compiler/src/dotty/tools/dotc/core/Types.scala

@@ -41,9 +41,11 @@ object Types {
 
   implicit def eqType: Eq[Type, Type] = Eq
 
-  /** The class of types.
+  /** Main class representing types.
+   *
    *  The principal subclasses and sub-objects are as follows:
    *
+   *  ```none
    *  Type -+- ProxyType --+- NamedType ----+--- TypeRef
    *        |              |                 \
    *        |              +- SingletonType-+-+- TermRef
@@ -74,6 +76,7 @@ object Types {
    *                       +- NoPrefix
    *                       +- ErrorType
    *                       +- WildcardType
+   *  ```
    *
    *  Note: please keep in sync with copy in `docs/docs/internals/type-system.md`.
    */

compiler/src/dotty/tools/dotc/transform/IsInstanceOfEvaluator.scala

@@ -7,36 +7,37 @@ import core._
 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:
- *  2.  a) Sel/sc is a value class or scrutinee is `Any`
- *      b) handleStaticallyKnown
- *      c) falseIfUnrelated with `scrutinee <:< selector`
- *      d) handleFalseUnrelated
- *      e) leave as is (aka `happens`)
- *  3.  Rewrite according to step taken in `2`
+ *  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._
 
-  def phaseName = "isInstanceOfEvaluator"
+  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.
+   */
   override def transformTypeApply(tree: TypeApply)(implicit ctx: Context, info: TransformerInfo): Tree = {
     val defn = ctx.definitions
 

doc-tool/resources/_includes/header.html

@@ -0,0 +1 @@
+<h1>Some header</h1>