Actualize ReadMe files

- Actualize build requirements and steps
- Extract Gradle plugin readme to the corresponding folder
- Rewrite Libraries and Maven Tools readme

#KT-20995 Fixed

ReadMe.md

@@ -29,7 +29,6 @@ Welcome to [Kotlin](https://kotlinlang.org/)! Some handy links:
 
 In order to build Kotlin distribution you need to have:
 
-- Apache Ant 1.9.4 and higher
 - JDK 1.6, 1.7 and 1.8
 - Setup environment variables as following:
 
@@ -46,20 +45,25 @@ You also can use [Gradle properties](https://docs.gradle.org/current/userguide/b
 
 ## Building
 
-On the first project configuration gradle will download and setup the dependencies on
-
-* `intellij-core` is a part of command line compiler and contains only necessary APIs.
-* `idea-full` is a full blown IntelliJ IDEA Community Edition to be used in the plugin module.
-
-Then, you may run Gradle to build the project and run tests, using:
+The project is built with Gradle. Run Gradle to build the project and to run the tests 
+using the following command on Unix/macOS:
 
     ./gradlew <tasks-and-options>
     
-command on Unix/macOS, or
+or the following command on Windows:
 
     gradlew <tasks-and-options>
+
+On the first project configuration gradle will download and setup the dependencies on
+
+* `intellij-core` is a part of command line compiler and contains only necessary APIs.
+* `idea-full` is a full blown IntelliJ IDEA Community Edition to be used in the plugin module.
+
+These dependencies are quite large, so depending on the qualify of your internet connection 
+you might face timeouts getting them. In this case you can increase timeout by specifying the following 
+command line parameters on the first run: 
     
-on Windows.
+    ./gradlew -Dhttp.socketTimeout=60000 -Dhttp.connectionTimeout=60000
 
 ## Important gradle tasks
 
@@ -73,13 +77,10 @@ on Windows.
 - `compilerTest` - build and run all compiler tests
 - `ideaPluginTest` - build and run all IDEA plugin tests
 
-**OPTIONAL:** Some artifacts, mainly Maven plugin ones, are built separately by Maven: go into `libraries` directory after building the compiler and run:
-
-    mvn install
-
+**OPTIONAL:** Some artifacts, mainly Maven plugin ones, are built separately with Maven.
 Refer to [libraries/ReadMe.md](libraries/ReadMe.md) for details.
 
-## Working with the project in IntelliJ IDEA
+## <a name="working-in-idea"></a> Working with the project in IntelliJ IDEA
 
 Working with the Kotlin project requires IntelliJ IDEA 2017.3. You can download IntelliJ IDEA 2017.3 [here](https://www.jetbrains.com/idea/download).
 
@@ -90,7 +91,7 @@ In the import dialog, select `use default gradle wrapper`.
 
 To be able to run tests from IntelliJ easily, check `Delegate IDE build/run actions to Gradle` in the Gradle runner settings.
 
-At this time, you can use the latest released 1.1.x version of the Kotlin plugin for working with the code. To make sure you have the latest version installed, use Tools | Kotlin | Configure Kotlin Plugin Updates and press "Check for updates now".
+At this time, you can use the latest released 1.2.x version of the Kotlin plugin for working with the code. To make sure you have the latest version installed, use Tools | Kotlin | Configure Kotlin Plugin Updates and press "Check for updates now".
 
 ### Compiling and running
 

libraries/ReadMe.md

 ## Kotlin Libraries
 
-This area of the project is all written in Kotlin and assumes you've got the [Kotlin IDEA plugin installed](../ReadMe.md#installing-plugin).
+This part of the project contains the sources of the following libraries:
 
-This area of the project uses Gradle and Maven for its build. When you open this project directory in IDEA the first time, it suggests you to import both gradle and maven projects. After importing you'll be able to explore and run gradle tasks and maven goals directly from IDEA with the instruments on the right sidebar.
+  - [kotlin-stdlib](stdlib), the standard library for Kotlin/JVM, Kotlin/JS and its additional parts for JDK 7 and JDK 8
+  - [kotlin-reflect](reflect), the library for full reflection support
+  - [kotlin-test](kotlin.test), the library for multiplatform unit testing
+  - [kotlin-annotations-jvm](tools/kotlin-annotations-jvm), the annotations to improve types in the Java code to look better when being consumed in the Kotlin code.
+  
+<!--  - [kotlin-annotations-android](tools/kotlin-annotations-android) -->
 
-### Building
+These libraries are built as a part of the [root](../) Gradle project.
 
-You need to install a recent [Maven](http://maven.apache.org/) distribution and setup environment variables as following:
 
-    JAVA_HOME="path to JDK 1.8"
-    JDK_16="path to JDK 1.6"
-    JDK_17="path to JDK 1.7"
-    JDK_18="path to JDK 1.8"
+## Kotlin Maven Tools
 
-The main part of the Kotlin standard library, `kotlin-stdlib`, is compiled against JDK 1.6 and also there are two extensions
-for the standard library, `kotlin-stdlib-jdk7` and `kotlin-stdlib-jdk8`, which are compiled against JDK 1.7 and 1.8 respectively,
-so you need to have all these JDKs installed.
+<!-- TODO: Move to another root -->
 
-Be sure to build Kotlin compiler distribution before launching Gradle and Maven: see [root ReadMe.md, section "Building"](../ReadMe.md#installing-plugin).
+This area of the project is the root for Maven build. 
 
-Core libraries are built with gradle, you can run that build using the gradle wrapper script even without local gradle installation:
-    
-    ./gradlew build install
-    
-> Note: on Windows type `gradlew` without the leading `./`
-    
-This command executes the `build` task, which assembles the artifacts and run the tests, and the `install` task, which puts the artifacts to the local maven repository to be used by the subsequent maven build.
+You can work with the maven modules of this maven project in IDEA from the [root IDEA project](../ReadMe.md#working-in-idea). After importing you'll be able to explore maven projects and run goals directly from IDEA with the instruments on the right sidebar.
 
-The rest of tools and libraries are built with maven:
+### Building
 
-    mvn install
+You need to install a recent (at least 3.3) [Maven](http://maven.apache.org/) distribution. 
 
-If your maven build is failing with Out-Of-Memory errors, set JVM options for maven in `MAVEN_OPTS` environment variable like this:
+Before building this Maven project you need to build and install the required artifacts built with Gradle to the local maven repository, by issuing the following command in the root project:
 
-    MAVEN_OPTS="-Xmx2G"
+    ./gradlew install
 
-## Gradle Plugin
-
-The Gradle plugin sources can be found at the [kotlin-gradle-plugin](tools/kotlin-gradle-plugin) module.
+> Note: on Windows type `gradlew` without the leading `./`
 
-To install the Gradle plugin into the local Maven repository, run inside the root Kotlin project:
+This command assembles and puts the artifacts to the local maven repository to be used by the subsequent maven build.
+See also [root ReadMe.md, section "Building"](../ReadMe.md#building).
 
-    ./gradlew :kotlin-gradle-plugin:install
     
-The subplugin modules are `:kotlin-allopen`, `:kotlin-noarg`, `:kotlin-sam-with-receiver`. To install them, run:
-
-    ./gradlew :kotlin-allopen:install :kotlin-noarg:install :kotlin-sam-with-receiver:install
-
-### Gradle integration tests
+Then you can build maven artifacts with Maven:
 
-Gradle integration tests can be found at the [kotlin-gradle-plugin-integration-tests](tools/kotlin-gradle-plugin-integration-tests) module.
+    mvn install
 
-Run the integration tests from the root project:
+If your maven build is failing with Out-Of-Memory errors, set JVM options for maven in `MAVEN_OPTS` environment variable like this:
 
-    ./gradlew :kotlin-gradle-plugin-integration-tests:test
-    
-The tests that use the Gradle plugins DSL ([`PluginsDslIT`](https://github.com/JetBrains/kotlin/blob/master/libraries/tools/kotlin-gradle-plugin-integration-tests/src/test/kotlin/org/jetbrains/kotlin/gradle/PluginsDslIT.kt)) also require the Gradle plugin marker artifacts to be installed:
+    MAVEN_OPTS="-Xmx2G"
 
-    ./gradlew -Pdeploy_version=1.2-test :kotlin-gradle-plugin:plugin-marker:install :kotlin-noarg:plugin-marker:install :kotlin-allopen:plugin-marker:install
-    ./gradlew -Pdeploy_version=1.2-test :kotlin-gradle-plugin-integration-tests:test

libraries/stdlib/ReadMe.md

 ## The Kotlin Standard Library
 
-This module creates the [standard library for kotlin](http://kotlinlang.org/api/latest/jvm/stdlib/index.html).
+This module creates the [standard library for Kotlin](http://kotlinlang.org/api/latest/jvm/stdlib/index.html).
 
 ### Notes for contributors
 

libraries/tools/kotlin-gradle-plugin/ReadMe.md

+## Gradle Plugin
+
+The Gradle plugin sources can be found in this ([kotlin-gradle-plugin](./)) module.
+
+To install the Gradle plugin into the local Maven repository, run this command from the root of Kotlin project:
+
+    ./gradlew :kotlin-gradle-plugin:install
+    
+The subplugin modules are `:kotlin-allopen`, `:kotlin-noarg`, `:kotlin-sam-with-receiver`. To install them, run:
+
+    ./gradlew :kotlin-allopen:install :kotlin-noarg:install :kotlin-sam-with-receiver:install
+
+To find more details about the plugins provided by this artifact and their tasks refer to [Module.md](Module.md).
+
+### Gradle integration tests
+
+Gradle integration tests can be found at the [kotlin-gradle-plugin-integration-tests](../kotlin-gradle-plugin-integration-tests) module.
+
+Run the integration tests from the root project:
+
+    ./gradlew :kotlin-gradle-plugin-integration-tests:test
+    
+The tests that use the Gradle plugins DSL ([`PluginsDslIT`](../kotlin-gradle-plugin-integration-tests/src/test/kotlin/org/jetbrains/kotlin/gradle/PluginsDslIT.kt)) also require the Gradle plugin marker artifacts to be installed:
+
+    ./gradlew -Pdeploy_version=1.2-test :kotlin-gradle-plugin:plugin-marker:install :kotlin-noarg:plugin-marker:install :kotlin-allopen:plugin-marker:install
+    ./gradlew -Pdeploy_version=1.2-test :kotlin-gradle-plugin-integration-tests:test