Update documentation for importing projects into Eclipse

Closes gh-23706

import-into-eclipse.md

@@ -1,46 +1,49 @@
 # Spring Framework - Eclipse/STS Project Import Guide
 
 This document will guide you through the process of importing the Spring Framework
-projects into Eclipse or the Spring Tool Suite (STS). It is recommended that you have a
+projects into Eclipse or the Spring Tool Suite (_STS_). It is recommended that you
-recent version of Eclipse or STS. As a bare minimum you will need Eclipse with full Java
+have a recent version of Eclipse. As a bare minimum you will need Eclipse with full Java
-8 support, the AspectJ Development Tools (AJDT), and the Groovy Compiler.
+8 support, the Kotlin plugin, and the Groovy plugin.
 
-The following instructions have been tested against
+The following instructions have been tested against [STS](https://spring.io/tools) 4.3.2
-[Spring Tool Suite](https://spring.io/tools) (_STS_) 3.9.4 and 4.0.0.M11 with
+([download](https://github.com/spring-projects/sts4/wiki/Previous-Versions#spring-tools-432-changelog))
-[Eclipse Buildship](https://projects.eclipse.org/projects/tools.buildship) (Eclipse
+with [Eclipse Buildship](https://projects.eclipse.org/projects/tools.buildship). The
-Plug-ins for Gradle). The instructions should work with the latest Eclipse distribution
+instructions should work with the latest Eclipse distribution as long as you install
-as long as you install
 [Buildship](https://marketplace.eclipse.org/content/buildship-gradle-integration). Note
 that STS 4 comes with Buildship preinstalled.
 
 ## Steps
 
-_Within your locally cloned `spring-framework` working directory:_
+_When instructed to execute `./gradlew` from the command line, be sure to execute it within your locally cloned `spring-framework` working directory._
 
-1. Precompile `spring-oxm` with `./gradlew :spring-oxm:compileTestJava`
+1. Ensure that Eclipse launches with JDK 8.
-2. Import into Eclipse (File -> Import -> Gradle -> Existing Gradle Project -> Navigate
+   - For example, on Mac OS this can be configured in the `Info.plist` file located in the `Contents` folder of the installed Eclipse or STS application (e.g., the `Eclipse.app` file).
-   to directory -> Select Finish)
+1. Install the [Kotlin Plugin for Eclipse](http://marketplace.eclipse.org/content/kotlin-plugin-eclipse) in Eclipse.
-3. If prompted, exclude the `spring-aspects` module (or after the import by closing or
+1. Install the [Eclipse Groovy Development Tools](https://github.com/groovy/groovy-eclipse/wiki) in Eclipse.
-   deleting the project)
+1. Switch to Groovy 2.5 (Preferences -> Groovy -> Compiler -> Switch to 2.5...) in Eclipse.
-4. In the `spring-oxm` project, add the `jaxb` folder in
+1. Change the _Forbidden reference (access rule)_ in Eclipse from Error to Warning
-   `build/generated-sources` to the build path (right click on them and select
+(Preferences -> Java -> Compiler -> Errors/Warnings -> Deprecated and restricted API -> Forbidden reference (access rule)).
-   `Build Path -> Use as Source Folder`)
+1. Optionally install the [AspectJ Development Tools](https://www.eclipse.org/ajdt/downloads/) (_AJDT_) if you need to work with the `spring-aspects` project.
-5. To apply project specific settings run `./gradlew eclipseBuildship`
+1. Optionally install the [TestNG plugin](https://testng.org/doc/eclipse.html) in Eclipse if you need to execute TestNG tests in the `spring-test` module.
-7. Code away
+1. Build `spring-oxm` from the command line with `./gradlew :spring-oxm:check`.
+1. To apply project specific settings, run `./gradlew eclipseBuildship` from the command line.
+1. Import into Eclipse (File -> Import -> Gradle -> Existing Gradle Project -> Navigate to the locally cloned `spring-framework` directory -> Select Finish).
+   - If you have not installed AJDT, exclude the `spring-aspects` project from the import, if prompted, or close it after the import.
+   - If you run into errors during the import, you may need to set the _Java home_ for Gradle Buildship to the location of your JDK 8 installation in Eclipse (Preferences -> Gradle -> Java home).
+1. If you need to execute JAXB-related tests in the `spring-oxm` project and wish to have the generated sources available, add the `build/generated-sources/jaxb` folder to the build path (right click on the `jaxb` folder and select `Build Path -> Use as Source Folder`).
+   - If you do not see the `build` folder in the `spring-oxm` project, ensure that the "Gradle build folder" is not filtered out from the view. This setting is available under "Filters" in the configuration of the Package Explorer (available by clicking on the small downward facing arrow in the upper right corner of the Package Explorer).
+1. Code away!
 
 ## Known Issues
 
 1. `spring-core` and `spring-oxm` should be pre-compiled due to repackaged dependencies.
    - See `*RepackJar` tasks in the build.
-2. `spring-aspects` does not compile due to references to aspect types unknown to Eclipse.
+1. `spring-aspects` does not compile due to references to aspect types unknown to Eclipse.
-  - If you install [AJDT](https://www.eclipse.org/ajdt/downloads/) into Eclipse it should
+   - If you installed _AJDT_ into Eclipse it should work.
-    work.
+1. While JUnit tests pass from the command line with Gradle, some may fail when run from
-3. While JUnit tests pass from the command line with Gradle, some may fail when run from
    the IDE.
    - Resolving this is a work in progress.
-  - If attempting to run all JUnit tests from within the IDE, you will likely need to set
+   - If attempting to run all JUnit tests from within the IDE, you may need to set the following VM options to avoid out of memory errors: `-XX:MaxPermSize=2048m -Xmx2048m -XX:MaxHeapSize=2048m`
-    the following VM options to avoid out of memory errors:
-	`-XX:MaxPermSize=2048m -Xmx2048m -XX:MaxHeapSize=2048m`
 
 ## Tips