Merge pull request #2422 from biboudis/docs-update

Fix #2180: Docs update

Author: felixmulder

docs/docs/contributing/backend.md

@@ -1,11 +1,14 @@
 ---
 layout: doc-page
-title: Working with the backend
+title: Working with the Backend
 ---
 
 The compiler backend is based on a fork of the Scala 2.11 `GenBCode` backend and
-lives at https://github.com/lampepfl/scala/tree/sharing-backend. The dotty
-source tree contains a git submodule in the directory
+lives at 
+
+> https://github.com/lampepfl/scala/tree/sharing-backend. 
+
+The dotty source tree contains a git submodule in the directory
 [scala-backend](https://github.com/lampepfl/dotty/tree/master/scala-backend)
 that points to this fork. We do not compile every file in this submodule,
 instead we add the subset of files we need to the dotty-compiler project in the
@@ -16,39 +19,44 @@ their content is not automatically updated when you do `git checkout` or `git
 pull`, instead everytime you switch branch, you need to do:
 
 ``` shell
-git submodule update --init
+$ git submodule update --init
 ```
 
 ## Environment setup
 
-1. Set the following git configuration options to make working with submodules
-easier, see the [Git Book](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
+1. Set the following git configuration options to make working with submodules easier, 
+see the [Git Book](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
 for more information:
 ``` shell
-git config --global diff.submodule log
-git config --global status.submodulesummary 1
-git config --global push.recurseSubmodules check
+$ git config --global diff.submodule log
+$ git config --global status.submodulesummary 1
+$ git config --global push.recurseSubmodules check
 ```
 
-2. Fork https://github.com/lampepfl/scala (in the following commands,
-   `dotty-staging/scala` is used as a placeholder for your
-   own fork).
-3. ```shell
-   cd scala-backend
-   git remote add scala-staging [email protected]:dotty-staging/scala.git
-   cd ..
-   ```
+2. Fork scala from github
+
+> https://github.com/lampepfl/scala 
+
+(in the following commands, `dotty-staging/scala` is used as a placeholder for your own fork).
+
+3. Add the new remote to track the upstream branch
+```shell
+$ cd scala-backend
+$ git remote add scala-staging [email protected]:dotty-staging/scala.git
+$ cd ..
+```
 
 ## Workflow when changing to the backend
 
 ```shell
-cd scala-backend
-git checkout -b my-feature-branch
+$ cd scala-backend
+$ git checkout -b my-feature-branch
+
 # Make some changes ...
+$ git push -u scala-backend
 
-git push -u scala-backend
 # Open a PR against https://github.com/lampepfl/scala/tree/sharing-backend
-cd ..
+$ cd ..
 ```
 
 Once your PR has been merged into the backend, you'll need to make another PR

docs/docs/contributing/debug-tests.md

@@ -14,14 +14,14 @@ Both are usually pre-installed on Mac OS and linux distributions.
 
 First, compile the file `tests/debug/while.scala`:
 
-```
-bin/dotc tests/debug/while.scala
+```shell
+$ dotc tests/debug/while.scala
 ```
 
 Second, run the compiled class with debugging enabled (suppose the main class is `Test`):
 
-```
-bin/dotr -d Test
+```shell
+dotr -d Test
 ```
 
 Third, start JDB:
@@ -36,7 +36,7 @@ You can run `help` for commands that supported by JDB.
 
 ### 1. Annotate the source code with debug information.
 
-Following file (`tests/debug/while.scala`) is an example of annoated source code:
+Following file (`tests/debug/while.scala`) is an example of annotated source code:
 
 ```Scala
 object Test {

docs/docs/contributing/eclipse.md

@@ -3,30 +3,58 @@ layout: doc-page
 title: Building Dotty with Eclipse
 ---
 
-Build setup
+Setup
 -----------
 
-1. Run `sbt ;managedSources;eclipse`
+You can setup Eclipse by using _[Scala IDE for Eclipse](http://scala-ide.org/)_ directly to run Dotty. Alternatively you can download 
+your Eclipse distribution of choice and enable the Scala IDE from the Eclipse Marketplace, separately.
 
-2. It is recommended to change the default output folder (in `Properties > java
+1. Clone Dotty's repository from Github (and run `sbt managedSources` as described in 
+[Getting Started](getting-started.md)) 
+2. Generate the Eclipse configuration files:
+```shell
+$ sbt eclipse
+```
+
+- Note: It is recommended to change the default output folder (in `Properties > java
    build path > Source`) to `dotty/classes` instead of `dotty/bin` because
    `dotty/bin` is reserved for shell scripts.
 
-If you have `CLASSPATH` defined:
+Optional: if you have `CLASSPATH` defined:
 
-3. Update your classpath to contain any new required external libraries to run
+1. Update your classpath to contain any new required external libraries to run
    `./bin/dotc`, `./bin/dotr` outside of Eclipse.
 
-4. Open the `Run Configurations` tab, and edit the `tests` configuration so
+1. Open the `Run Configurations` tab, and edit the `tests` configuration so
    that it contains a `CLASSPATH` variable which reflects the current
    `CLASSPATH`.
+   
+   
+Import to Eclipse
+-----------------
+
+First step is to import dotty to Eclipse. This is done by selecting `File > Import` from the menu and selecting
+_Existing Projects into Workplace_. 
+
+![](../../images/eclipse/eclipse-import.png "Import Dotty to Eclipse")
+
+On the next window, select the bare minimum configuration to run Dotty. You will need the compiler, library and the 
+interfaces.
+
+![](../../images/eclipse/eclipse-select.png "Import Dotty Projects")
+
+
+Running/Debugging
+---------------------------------------------------
+
+To run/debug Dotty you have to create a new configuration from `Run > Run Configurations`. First select the project on the
+package explorer and then select the aforementioned option. On the `Main` tab you must have `dotty-compiler` for the 
+_Project_ and `dotty.tools.dotc.Main` for the _Main class_. Specify the arguments you want for the compiler on the
+`Arguments` tab (e.g, flags and source files) and then proceed to the `Classpath` tab. There you must 
+specify three `Bootstrap Entries` which are the compiler, interfaces and the library as shown in the screenshot below. 
+Additionally you need to specify the scala-asm library as an external jar dependency. This can be found on your local
+`~/.ivy2/cache/` directory.
+
+![](../../images/eclipse/eclipse-runconfiguration.png "Import Dotty Projects")
 
-Running the compiler Main class from Eclipse
---------------------------------------------
-1. Navigate to `dotty.tools.dotc.Main`
-2. `Run As... > Scala Application`
-3. `Run Configurations > Main$ > Classpath > Bootstrap entries`:
-   - Add the Scala library (`Advanced...` > `Add library...` > `Scala library`)
-   - Add the Dotty classfiles (`Add projects...` > `[x] dotty`)
-4. `Run Configurations > Main$ > Arguments` and add
-   `${project_loc}/tests/pos/HelloWorld.scala`
+The compiler can be run and debugged using the same configuration. To contribute to dotty please follow the [Dotty Developer Guidelines](https://github.com/lampepfl/dotty/blob/master/CONTRIBUTING.md).

docs/docs/contributing/getting-started.md

@@ -3,20 +3,9 @@ layout: doc-page
 title: Getting Started
 ---
 
-Talks on Dotty
---------------
-- [Scala's Road Ahead](https://www.youtube.com/watch?v=GHzWqJKFCk4) by Martin Odersky [\[slides\]](http://www.slideshare.net/Odersky/scala-days-nyc-2016)
-- [Compilers are Databases](https://www.youtube.com/watch?v=WxyyJyB_Ssc) by Martin Odersky [\[slides\]](http://www.slideshare.net/Odersky/compilers-are-databases)
-- [Dotty: Exploring the future of Scala](https://www.youtube.com/watch?v=aftdOFuVU1o) by Dmitry Petrashko [\[slides\]](https://d-d.me/scalaworld2015/#/). This talk includes details about the design of mini-phases and denotations.
-- [Making your Scala applications smaller and faster with the Dotty linker](https://www.youtube.com/watch?v=xCeI1ArdXM4) by Dmitry Petrashko [\[slides\]](https://d-d.me/scaladays2015/#/)
-- [Dotty: what is it and how it works](https://www.youtube.com/watch?v=wCFbYu7xEJA) by Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/dotty-tutorial/#/)
-- [Hacking on Dotty: A live demo](https://www.youtube.com/watch?v=0OOYGeZLHs4) by Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/dotty-live-demo/)
-- [AutoSpecialization in Dotty](https://vimeo.com/165928176) by Dmitry Petrashko [\[slides\]](https://d-d.me/talks/flatmap2016/#/)
-- [Dotty and types: the story so far](https://www.youtube.com/watch?v=YIQjfCKDR5A) by Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/typelevel-summit-oslo/)
-
 Requirements
 ------------
-Make sure that you are using Java 8 or later, the output of `java -version`
+Make sure that you are using Java 8 or later. The output of `java -version`
 should contain `1.8`.
 
 Compiling and Running
@@ -26,11 +15,11 @@ Start by cloning the repository:
 ```bash
 $ git clone --recursive https://github.com/lampepfl/dotty.git
 $ cd dotty
-$ sbt managedSources ## Needed for IDE import to succeed
+$ sbt managedSources # Needed for IDE import to succeed
 ```
 
 Dotty provides a standard sbt build: compiling, running and starting a repl can
-all be done from within sbt using
+all be done from within sbt:
 
 ```bash
 $ sbt
@@ -39,13 +28,21 @@ $ sbt
 hello world
 ```
 
-there is also a bash script that can be used in the same way:
+There are also bash scripts that can be used in the same way. Assuming that you have cloned the Dotty repo locally, append 
+the following line on your `.bash_profile`:
 
-```bash
+```shell
+$ export PATH=$HOME/dotty/bin:$PATH
+```
+
+and you will be able to run the corresponding commands directly from your console:
+
+```shell
 # Compile code using Dotty
-./bin/dotc tests/pos/HelloWorld.scala
+$ dotc tests/pos/HelloWorld.scala
+
 # Run it with the proper classpath
-./bin/dotr HelloWorld
+$ dotr HelloWorld
 ```
 
 
@@ -63,5 +60,5 @@ scala>
 or via bash:
 
 ```bash
-$ ./bin/dotr
+$ dotr
 ```

docs/docs/contributing/intellij-idea.md

@@ -3,33 +3,59 @@ layout: doc-page
 title: Building Dotty with Intellij IDEA
 ---
 
-Dotty compiler support is available in the [Scala plugin nightly] starting
-from 2.2.39. You need to install [IDEA 2016.1] to try it.
+Setup
+-----
 
-## To create a new project with Dotty
+You can setup IntelliJ [IDEA >= 2016.1](https://www.jetbrains.com/idea/nextversion) to run Dotty.
 
-1. Open New Project dialog and select `Scala` > `Dotty`
-2. Proceed as usual and don't forget to create or select Dotty SDK.
+Assuming you have cloned dotty's repository from Github (and run `sbt managedSources` as described in [Getting Started](getting-started.md)),
+you can now proceed with importing it to IDEA by selecting the
+corresponding option from the startup menu. Navigate on the corresponding directory and select it. Next, you need
+to select the model of the import and as the screenshot shows, select SBT.
 
-## To compile an existing Scala project with Dotty
+![](../../images/idea/idea-import.png "Import Dotty in IDEA")
 
-1. Create a new Dotty SDK:
-   `Project Structure` > `Global libraries` > `New Global Library` > `Dotty SDK`
-2. Replace Scala SDK with Dotty SDK in:
-   `Project Structure` > `Modules` > `Dependencies`
+Next, you select the version of the JDK that this project relies on and verify that you have selected 1.8 (assuming
+its installed on your local machine). Otherwise, specify it by pressing *New*.
 
-Java 1.8 should be used as the Project/Module SDK. You also need to enable the
-Scala Compile Server to use Dotty compiler.
+![](../../images/idea/idea-sdk.png "Select the JDK")
 
-## Notes
-* Dotty support is experimental, many features including code highlighting and
-  worksheet are not ready yet.
-* You can download the latest version of Dotty without creating a new Dotty SDK
-  with the `Update snapshot` button in the Dotty SDK library settings.
-* Please report any problems to the [IntelliJ Scala issue tracker] or write
-  to the [IntelliJ Scala gitter]
+On the final window we must select which modules we can import. Here, we are presented with the full list of SBT projects
+that are defined in Dotty. You can either select all (expect performance degradation by IDEA if you select all) or
+select only the `dotty` module. In order to do that, unselect all modules and select on `dotty`. IDEA, then, automatically
+selects all the necessary dependencies and you press OK.
 
-[Scala plugin nightly]: https://confluence.jetbrains.com/display/SCA/Scala+Plugin+Nightly
-[IDEA 2016.1]: https://www.jetbrains.com/idea/nextversion/
-[IntelliJ Scala issue tracker]: https://youtrack.jetbrains.com/issues/SCL
-[IntelliJ Scala gitter]: https://gitter.im/JetBrains/intellij-scala
+![](../../images/idea/idea-sbt.png "Select modules to import")
+
+Running/Debugging
+-------
+
+To run the compiler you can do it either as an sbt command or via debugging the compiler.
+For the first option you can fire up sbt from the `Terminal` window of IDEA or you can do it externally.
+For example, to run a test you can write with or without flags:
+
+```shell
+dotc tests/pos/Arrays.scala
+```
+
+If you are interested in debugging the compiler you can enable the necessary agent on the JVM.
+This is done in two steps. For the first step you need to pass the 
+necessary flag to the running VM. For convenience, this is already in comments on the `Build.scala` file under the
+`project` directory. The string you need to uncomment is the following:
+
+> `"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005"`
+
+Uncomment the line and reload the project file with the `reload` command on sbt. 
+Now, each time you run `dotc` the compiler listens at the designated address and waits the agent to connect.
+For, the second step you need to create a configuration for Debug through IDEA: 
+
+> Run > Edit Configurations > Add New Configuration > (select) Remote
+
+![](../../images/idea/idea-debug.png "Create a Debug Configuration")
+
+Now every time you run `dotc` you can set your breakpoints and hit the `Debug dotty-debug` button (since we used that name for 
+ the sample configuration above). The default data on the configuration match the enabled agent on the VM so, probably,
+ you will not need to change anything else.
+ 
+To contribute to dotty please follow the [Dotty Developer Guidelines](https://github.com/lampepfl/dotty/blob/master/CONTRIBUTING.md).
+