Merge pull request #135 from apache/documentation-updates

Minor updates to documentation
apache · Aug 2, 2021 · 6b92a68b628455a6d7be5e9cf77282245863be70 · 6b92a68
2 parents 771429e + 33591ef
commit 6b92a68b628455a6d7be5e9cf77282245863be70
Showing 14 changed files with 58 additions and 28 deletions.
diff --git a/README.md b/README.md
@@ -42,7 +42,7 @@ If you are interested in making contributions to this site please see our [Commu
 
 Datasketches memory currently supports Java 8 up to and including Java 13.
 
-In order to use the library in Java 9 and above, you must provide the following runtime arguments to the JVM:
+In order to allocate off-heap memory using the library in Java 9 and above, you must provide the following runtime arguments to the JVM:
 
 ```shell
     --add-opens java.base/java.nio=org.apache.datasketches.memory \
@@ -69,6 +69,7 @@ module datasketches.memory.multirelease.test {
 }
 ```
 
+Note that the `add-opens` arguments are not required for cases where memory is allocated on the heap.
 
 ---
 
@@ -83,6 +84,8 @@ This DataSketches component is pure Java and requires the following JDKs to comp
 - JDK9/Hotspot
 - JDK11/Hotspot
 
+Ensure that your local environment has been configured according to the [Maven toolchain configuration](docs/maven-toolchains.md).
+
 ### Recommended Build Tool
 This DataSketches component is structured as a Maven project and Maven is the recommended Build Tool.
 
@@ -119,7 +122,7 @@ This will create the following Jars:
 ### Toolchains
 
 This project makes use of Maven toolchains to ensure that the correct Java compiler version is used when compiling source files.
-Ensure that your local environment has been configured according to the [Maven toolchain configuration](docs/maven-toolchains.md).
+See the [Maven toolchain configuration](docs/maven-toolchains.md) for more details.
 
 ### Dependencies
 

diff --git a/docs/eclipse.md b/docs/eclipse.md
@@ -1,12 +1,11 @@
 # Eclipse IDE setup
 
-The use of Maven submodules to build a Multi Release JAR was motivated by its compatibility with popular IDEs.
+The use of Maven submodules to build a Multi Release JAR was motivated by its compatibility with popular IDEs. There are two configuration properties to be aware of when 
+configuring your local development environment:
 
-There are two configuration properties to be aware of when configuring your local development environment:
+### Java compiler versions
 
-#### Java compiler versions
-
-Settings are usually synchronised with maven toolchain configuration, otherwise the Java version for a maven module
+Settings are usually synchronised with Maven Toolchain configuration, otherwise the Java version for a Maven module
 should be set as follows:
 
 | Maven submodule                   | JDK |
@@ -19,7 +18,7 @@ should be set as follows:
 | datasketches-memory-java11		|  11 |
 | datasketches-memory-resources     |  8  |
 
-#### Compiler arguments for JPMS
+### Compiler arguments for JPMS
 
 In order to compile Maven modules in Java versions 9 and above, it is necessary to provide the following arguments to the
 compiler.  These are usually synchronised with the `pom.xml` configuration:
@@ -33,11 +32,11 @@ compiler.  These are usually synchronised with the `pom.xml` configuration:
 
 ---
 
-## Eclipse configuration
+## Running Datasketches-Memory in Eclipse
 
 Note that the following configuration was verified using Eclipse Version: 2020-12 (4.18.0)
 
-#### The eclipse maven plugin
+### The eclipse maven plugin
 
 The [Eclipse Maven plugin](https://maven.apache.org/plugins/maven-eclipse-plugin/) is used to generate Eclipse IDE files.  In order to run the eclipse plugin use:
 
@@ -49,28 +48,43 @@ Please note that this plugin is retired and no longer maintained!
 
 ---
 
-#### Required - Compiler arguments for JPMS
+### Importing the project into eclipse
+
+From the **Package Explorer** View:
+
+- Right click on a blank space in the view
+- Select **Import/Maven/Existing Maven Projects**
+- Select **Next**, and browse to the project directory
+- Click **Open**
+
+---
+
+### Setting compiler arguments for JPMS
 
 Although these should be set automatically, the Eclipse IDE does not currently configure these settings according to the `pom.xml` - see this [Eclipse Bug](https://github.com/eclipse-m2e/m2e-core/issues/129).
 Ensure that the required JPMS arguments are set for the compiler (Java 9 only).
 
-First, open the project properties dialog for the `datasketches-memory-java9` project, and click on `Java Build Path`. Next, open the `Module Dependencies` tab and add an export for `java.base/jdk.internal.ref`:
+- First, right-click on the `datasketches-memory-java9` project, and select **Properties/Java Build Path**. 
+- Next, open the **Module Dependencies** tab and select the `java.base` package.
+- Click on **Configured details**, followed by **Expose package**.
+- In the dialog box, enter package: ```jdk.internal.ref```, and `org.apache.datasketches.memory` as the target module.
+- Ensure that the **exports** checkbox is selected.
 
 ![Eclipse java compiler arguments](img/eclipse-java-compiler-arguments-1.png "Eclipse project compiler arguments")
 
-Finally, click `Apply and Close`:
+- Finally, click **Apply and Close**:
 
 ![Eclipse java compiler arguments](img/eclipse-java-compiler-arguments-2.png "Eclipse project compiler arguments")
 
 Note: These arguments need only be supplied for `datasketches-memory-java9`.
 
 ---
 
-#### Verify - Java compiler settings
+### Setting Java compiler settings
 
 This should be set automatically by the IDE.  However, you may ensure that the correct Java compliance level is set for each module by using the Eclipse `Java Compiler` dialog.
 
-Open the `Java Compiler` dialog, and ensure `Enable project specific settings` is checked:
+- Open the **Java Compiler** dialog, and ensure **Enable project specific settings** is checked:
 
 ![Eclipse compiler level](img/eclipse-compiler-level.png "Eclipse Java Compiler Settings")
 
@@ -82,18 +96,26 @@ You might need to verify this for each module, making sure the correct complianc
 
 ---
 
-#### Verify - JRE library versions
+### Setting JRE library versions
 
-This should be set automatically by the IDE.  However, you may ensure that the correct JRE is used for each module by using the Eclipse `Java Build Path` dialog.
+This should be set automatically by the IDE.  However, you may ensure that the correct JRE is used for each module by using the Eclipse **Java Build Path** dialog.
 
-First, open the project properties dialog for the `datasketches-memory-java9` project, and click on `Java Build Path`. Next, open the `Libraries` tab and select the `JRE System Library` under `Modulepath`.  Click `Edit` and ensure that the `Execution Environment` is selected and set to Java 9:
+- First, open the project properties dialog for the `datasketches-memory-java9` project, and click on **Java Build Path**. 
+- Next, open the **Libraries** tab and select the **JRE System Library** under **Modulepath**.
+- Click **Edit** and ensure that the **Execution Environment** is selected and set to Java 9:
 
 ![Eclipse build path](img/eclipse-build-path-1.png "Java 9 Eclipse project build path")
 
-Follow a similar process for `datasketches-memory-java11`, and verify that `Execution Environment` is selected and set to Java 11:
+- Follow a similar process for `datasketches-memory-java11`, and verify that **Execution Environment** is selected and set to Java 11:
 
 ![Eclipse build path](img/eclipse-build-path-2.png "Java 11 Eclipse project build path")
 
-Lastly, for all other modules, verify that the `Execution Environment` is selected and set to the Java 8 JRE:
+- Lastly, for all other modules, verify that the **Execution Environment** is selected and set to the Java 8 JRE:
 
 ![Eclipse build path](img/eclipse-build-path-3.png "Java 8 Eclipse project build path")
+
+### Running unit tests
+
+- Under the `datasketches-memory-java-8-tests` module, right-click on the `src/test/java` directory.
+- Select **Run-As** / **TestNG Test**
+- It should open a new window and run over 400 tests without error.
diff --git a/docs/img/eclipse-build-path-1.png b/docs/img/eclipse-build-path-1.png
diff --git a/docs/img/eclipse-build-path-2.png b/docs/img/eclipse-build-path-2.png
diff --git a/docs/img/eclipse-build-path-3.png b/docs/img/eclipse-build-path-3.png
diff --git a/docs/img/eclipse-compiler-level.png b/docs/img/eclipse-compiler-level.png
diff --git a/docs/img/eclipse-java-compiler-arguments-1.png b/docs/img/eclipse-java-compiler-arguments-1.png
diff --git a/docs/img/eclipse-java-compiler-arguments-2.png b/docs/img/eclipse-java-compiler-arguments-2.png
diff --git a/docs/img/eclipse-project-structure.png b/docs/img/eclipse-project-structure.png
diff --git a/docs/img/intellij-java-compiler-arguments.png b/docs/img/intellij-java-compiler-arguments.png
diff --git a/docs/img/intellij-project-structure.png b/docs/img/intellij-project-structure.png
diff --git a/docs/intellij.md b/docs/intellij.md
@@ -33,17 +33,19 @@ compiler.  These are usually synchronised with the `pom.xml` configuration:
 
 ---
 
+## Running Datasketches-Memory in IntelljJ-IDEA
+
 Note that the following configuration was verified using IntelliJ IDEA 2021.1.2 (Community Edition).
 
-#### Java compiler versions
+### Java compiler versions
 
 Ensure that the correct SDK is used for each module using the IntelliJ project structure dialog:
 
 ![IntelliJ project structure dialog](img/intellij-project-structure.png "Intellij project structure dialogue")
 
 ---
 
-#### Compiler arguments for JPMS
+### Compiler arguments for JPMS
 
 Ensure that the required JPMS arguments are set for the compiler (Java 9 only).  These should be detected and set automatically based on the `pom.xml` configuration.
 

diff --git a/docs/maven-toolchains.md b/docs/maven-toolchains.md
@@ -42,15 +42,15 @@ For example, if you are using [SDKMAN!](https://sdkman.io/), your environment mi
 - JAVA11_HOME: `/Users/me/.sdkman/candidates/java/11.0.10.hs-adpt`
 
 #### For MacOS or Linux variants
-Users can discover what JDKs have been loaded into their enviornment by using the following command:
+Users can discover what JDKs have been loaded into their environment by using the following command:
 
 - /usr/libexec/java_home -V
 
 
 ### Eclipse configuration
 
-If you are an Eclipse user, you may need further configuration for your IDE to use the appropriate JDK for each module - see the [eclipse IDE setup](eclipse.md).
+If you are an Eclipse user, you may need further configuration for your IDE to use the appropriate JDK for each module - see the [Eclipse IDE setup](eclipse.md).
 
 ### IntelliJ configuration
 
-Similarly, if you are an Eclipse user, you may need further configuration for your IDE to use the appropriate JDK for each module - see the [eclipse IDE setup](eclipse.md).
+Similarly, if you are an Eclipse user, you may need further configuration for your IDE to use the appropriate JDK for each module - see the [IntelliJ IDE setup](intellij.md).
diff --git a/docs/module-system.md b/docs/module-system.md
@@ -72,19 +72,22 @@ to the Maven compiler plugin in the module's pom.xml file:
     </compilerArgs>
 ```
 
-### Runtime arguments
+### Runtime arguments (off-heap memory only)
 
-Reflection is used by the datasketches memory library in cases where fields and methods that do not have `public` visibility
+When allocating off-heap memory, reflection is used by the datasketches memory library in cases where fields and methods that do not have `public` visibility
 in a class.  Reflective access requires additional arguments to be provided by the user at runtime, in order to use the 
 `datasketches-memory` JPMS module in Java versions 9 and above.
 
-The following runtime arguments should be provided when using the library:
+The following runtime arguments should be provided when allocating memory off-heap:
+
 ```shell
     --add-opens java.base/java.nio=org.apache.datasketches.memory \
     --add-opens java.base/jdk.internal.misc=org.apache.datasketches.memory \
     --add-opens java.base/jdk.internal.ref=org.apache.datasketches.memory
 ```
 
+Note that these arguments are not required for cases where memory is allocated on the heap.
+
 ### JPMS and Java 8
 
 Java 8 does not support module declarations and the JPMS module system.