Polish text

docs/src/docs/asciidoc/gradle-plugin.adoc

@@ -8,7 +8,7 @@ image:https://github.com/graalvm/native-build-tools/actions/workflows/test-nativ
 
 The {doctitle} adds support for building and testing native images using the https://gradle.org[Gradle build tool].
 
-For upgrading please take a look at the <<changelog.adoc#,Changelog>>.
+To upgrade, please take a look at the <<changelog.adoc#,project changelog>>.
 
 [[quickstart]]
 == Quickstart
@@ -26,7 +26,7 @@ You can find full samples in https://github.com/graalvm/native-build-tools/tree/
 ====
 
 
-== Adding the plugin
+Adding the Plugin
 
 Add following to `plugins` section of your project's `build.gradle` / `build.gradle.kts`:
 
@@ -68,14 +68,14 @@ include::../snippets/gradle/kotlin/settings.gradle.kts[tags=pre-release, indent=
 ----
 ====
 
-== Installing GraalVM Native Image tool
+ Installing GraalVM
 
-By default, the plugin will try to use the `native-image` tool that is bundled with the JDK that is used to run Gradle.
+By default, the plugin attempts to use the `native-image` tool bundled with the JDK running Gradle. Therefore, you must ensure that Gradle runs on a GraalVM JDK.
 This means you must make sure that you run Gradle with a GraalVM JDK.
 
 Alternatively, you may choose to:
 
-1. Set up a `GRAALVM_HOME` environment variable pointing to your GraalVM installation, in which case the JDK pointed at this location will be used for Native Image builds instead
+1. Set the `GRAALVM_HOME` environment variable to point to your GraalVM installation. When this variable is configured, the JDK specified at this location will be used for Native Image builds.
 2. <<configuration-toolchains-enabling, Enable toolchain support>>
 
 [NOTE]
@@ -134,7 +134,7 @@ Again, be aware that the toolchain detection _cannot_ distinguish between GraalV
 [[configuration]]
 == Configuration
 
-This plugin works with the `application` plugin and will register a number of tasks and extensions for you to configure.
+This plugin works with the `application` plugin and registers a number of tasks and extensions for you to configure.
 
 === Available tasks
 
@@ -149,7 +149,7 @@ Those tasks are configured with reasonable defaults using the `graalvmNative` ex
 
 The main executable is configured by the image named `main`, while the test executable is configured via the image named `test`.
 
-=== Native image options
+=== Configure Native Image
 
 The link:javadocs/native-gradle-plugin/org/graalvm/buildtools/gradle/dsl/NativeImageOptions.html[NativeImageOptions] allows you to tweak how the native image is going to be built.
 The plugin allows configuring the final binary, the <<test-binary-config,tests>> one, as well as apply options to both.
@@ -182,74 +182,76 @@ include::../snippets/gradle/groovy/build.gradle[tags=all-config-options]
 include::../snippets/gradle/kotlin/build.gradle.kts[tags=all-config-options]
 ----
 
-Native Image options:
+==== Native Image options
 
-- `imageName` -The name of the native image, defaults to the project name
-- `mainClass` - The main class to use, defaults to the application.mainClass
-- `debug` - Determines if debug info should be generated, defaults to false (alternatively add --debug-native to the CLI)
-- `verbose` - Add verbose output (`false` by default)
-- `fallback` - Sets the fallback mode of native-image (`false` by default)
-- `sharedLibrary` - Determines if image is a shared library
-- `quickBuild` - Determines if image is being built in quick build mode
-- `richOutput` - Determines if native-image building should be done with rich output
-- `requiredVersion` - The minimal GraalVM version, can be `MAJOR`, `MAJOR.MINOR` or `MAJOR.MINOR.PATCH`
-- `systemProperties` - Sets the system properties to use for the native image builder
-- `configurationFileDirectories` - Adds a native image configuration file directory, containing files like reflection configuration
-- `excludeConfig` - Excludes configuration that matches one of given regexes from JAR of dependency with said coordinates.
-- `jvmArgs` - Passes the given argument directly to the JVM running the native image builder
-- `useFatJar` - Instead of passing each jar individually, builds a fat jar
+- `imageName` - The name of the native image, defaults to the project name
+- `mainClass` - The main class to use, defaults to the _application.mainClass_
+- `debug` - Determines if debug info should be generated; defaults to `false` (alternatively add `--debug-native` to the CLI)
+- `verbose` - Adds verbose output (`false` by default)
+- `fallback` - Sets the fallback mode of `native-image` (`false` by default)
+- `sharedLibrary` - Determines if the image is a shared library
+- `quickBuild` - Determines if the image is being built in quick build mode
+- `richOutput` - Determines whether `native-image` building should produce rich output
+- `systemProperties`: Defines the system properties to use for the `native-image` builder
+- `configurationFileDirectories`: Adds a directory containing configuration files for `native-image`, such as reflection configuration
+ -`excludeConfig`: Excludes configuration that matches any of the specified regex patterns from the JAR of a dependency with the given coordinates
+- `jvmArgs`: Passes the specified arguments directly to the JVM running the `native-image` builder
+- `useFatJar`: Builds a fat JAR instead of passing each JAR individually
 
 You can also pass **build-time** and **run-time** arguments:
 
+- `buildArgs.add('<buildArg>')`: Learn more about possible build arguments https://www.graalvm.org/latest/reference-manual/native-image/overview/BuildConfiguration/[here].
+- `runtimeArgs.add('<runtimeArg>')`: Specifies runtime arguments consumed by your application.
+
 - `buildArgs.add('<buildArg>')` - You can find more about possible build arguments https://www.graalvm.org/latest/reference-manual/native-image/overview/BuildConfiguration/[here]
 - `runtimeArgs.add('<runtimeArg>')` - Runtime arguments consumed by your application
 
 
 NOTE: For options that can be set using command-line, if both DSL and command-line options are present, command-line options take precedence.
 
-Native Image Agent options:
+==== Native Image Tracing Agent options
 
-* `defaultMode` - Default agent mode if one isn't specified using `-Pagent=mode_name`
+* `defaultMode` - Specifies the default agent mode if one isn't specified using `-Pagent=mode_name`
 * `enabled` - Enables the agent
-* `modes`- you can configure following agent modes:
+* `modes`- Configures the following agent modes::
     ** `standard` -The standard agent mode generates metadata without conditions
     ** `conditional` - The conditional agent mode generates metadata with conditions
-        *** `userCodeFilterPath` - Path to a filter file that determines classes which will be used in the metadata conditions
-        *** `extraFilterPath` - Optional, extra filter used to further filter the collected metadata
+        *** `userCodeFilterPath` - Path to a filter file that specifies which classes to include in metadata conditions
+        *** `extraFilterPath` - (Optional) An additional filter file to further refine the collected metadata
     ** `direct` - The direct agent mode allows users to directly pass options to the agent
-        *** `{output_dir}` - a special string expanded by the plugin to where the agent files would usually be output
-* `tasksToInstrumentPredicate` - By default, if `-Pagent` is specified, all tasks that extend JavaForkOptions are instrumented.
+        *** `{output_dir}` -  The output directory to store agent files
+* `tasksToInstrumentPredicate` - By default, when `-Pagent` is specified, all tasks extending `JavaForkOptions` are instrumented.
 This can be limited to only specific tasks that match this predicate.
 
 [TIP]
 Options like `callerFilterFiles`, `accessFilterFiles`, `builtinCallerFilter`, `builtinHeuristicFilter`, `enableExperimentalPredefinedClasses`, `enableExperimentalUnsafeAllocationTracing` and `trackReflectionMetadata`
 are common for all agent modes and intended to be used for more advanced purposes. You can read more about those options https://www.graalvm.org/latest/reference-manual/native-image/metadata/AutomaticMetadataCollection/#agent-advanced-usage[here].
 
 [[agent-support]]
-==== Reflection support and running with the native agent
+==== Reflection Registration with the Tracing Agent
 
-If your project requires reflection, classpath resources, dynamic proxies or other features requiring explicit native configuration, it may prove helpful to first run your application or tests using the https://www.graalvm.org/reference-manual/native-image/metadata/AutomaticMetadataCollection/[native-image-agent].
+If your project requires reflection, classpath resources, dynamic proxies, or other features that need explicit configuration, it may be helpful to first run your application or tests using the https://www.graalvm.org/reference-manual/native-image/metadata/AutomaticMetadataCollection/[Native Image Tracing Agent].
 
 The Native Image Gradle plugin simplifies generation of the required metadata files by injecting the agent automatically for you (this includes, but is not limited to the reflection file).
 
-Any task that extends `JavaForkOptions` (like `test`, `run` etc) can be instrumented by passing `-Pagent` to gradle when running said tasks.
+Any task that extends `JavaForkOptions` (such as `test`, `run`, etc.) can be instrumented by passing `-Pagent` to Gradle when running those tasks.
 
 The agent can run in multiple modes that dictate how the metadata is collected and merged.
 
 Once the metadata is collected, it can be copied into the project using the `metadataCopy` task.
 
 [source,bash, role="multi-language-sample"]
 ----
-./gradlew -Pagent run # Runs on JVM with native-image-agent.
+./gradlew -Pagent run # Runs on HotSpot with the agent
 ./gradlew metadataCopy --task run --dir src/main/resources/META-INF/native-image # Copies the metadata collected by the agent into the project sources
-./gradlew nativeCompile # Builds image using metadata acquired by the agent.
+./gradlew nativeCompile # Builds an image using the metadata acquired by the agent.
 
 # For testing
 ./gradlew -Pagent nativeTest # Runs on JVM with the native-image agent, collects the metadata and uses it for testing on native-image.
 ----
 
-The generated configuration files will be found in the `${buildDir}/native/agent-output/${taskName}` directory, for example, `build/native/agent-output/run`.
-The plugin will also substitute `{output_dir}` in the agent options to point to this directory during the agent run.
+The generated configuration files can be found in the `${buildDir}/native/agent-output/${taskName}` directory, for example, _build/native/agent-output/run_.
+The plugin also substitutes `{output_dir}` in the agent options to point to this directory during the agent run.
 
 [[max_parallel_builds]]
 ==== Max parallel builds
@@ -502,7 +504,7 @@ In order to generate a binary with instrumentation enabled, you should run the `
 
 `./gradlew nativeCompile --pgo-instrument`
 
-This will generate a binary under `build/native/nativeCompile` with the `-instrumented` suffix.
+This will generate a binary under _build/native/nativeCompile_ with the `-instrumented` suffix.
 You can run the binary to gather profiling data:
 
 [source,bash, role="multi-language-sample"]

docs/src/docs/asciidoc/index.adoc

@@ -1,9 +1,9 @@
 = Native Build Tools
 The GraalVM team
 
-The {doctitle} project provides plugins for different build tools to add support for building and testing native applications written in Java
-(or any other language compiled to JVM bytecode) using the https://www.graalvm.org/reference-manual/native-image/[GraalVM  Native Image].
-At the moment, you can build your native projects using our Gradle or Maven plugin.
+
+The {doctitle} project provides plugins for various build tools, enabling support for building and testing native applications written in Java (or any other language compiled to JVM bytecode) using https://www.graalvm.org/reference-manual/native-image/[GraalVM  Native Image].
+Currently, you can build your native applications using our Gradle or Maven plugins.
 
 Each plugin takes metadata for available libraries from the https://github.com/oracle/graalvm-reachability-metadata[GraalVM reachability metadata repository]
 to provide better experience during the development of your native project.
@@ -13,25 +13,25 @@ If you are using alternative build systems, see <<alternative-build-systems.adoc
 [discrete]
 === Documentation
 
-In case you are new to the Native Build Tools (either as an end user or a library author), read our:
+If you're new to the Native Build Tools, whether as an end user or a library author, check out our:
 
 - <<end-to-end-gradle-guide.adoc#,End-to-end Gradle guide>>
 - <<end-to-end-maven-guide.adoc#,End-to-end Maven guide>>
 
-For detailed documentation, please refer to the following pages of the specific build tools:
+For detailed documentation, see the corresponding page for each build tool:
 
 - <<gradle-plugin.adoc#,The Gradle plugin documentation>>
 - <<maven-plugin.adoc#,The Maven plugin documentation>>
 
-You can see the full changelog <<changelog.adoc#,here>>.
+For updates to the Native Build Tools between releases, see the full changelog <<changelog.adoc#,here>>.
 
 [discrete]
 === Contributing
 
 If you are interested in contributing or reporting an issue related to the plugins, please refer to the https://github.com/graalvm/native-build-tools[Native Build Tools repository].
-Also, be aware that all contributors must sign the https://oca.opensource.oracle.com/[Oracle Contributor Agreement] (OCA).
+Please note that all contributors must sign the https://oca.opensource.oracle.com/[Oracle Contributor Agreement] (OCA).
 
 [TIP]
 --
-Please be aware that this repository should be used to report issues related to the Maven or Gradle plugins for GraalVM.
-Please report issues which are specific to the framework itself (for example https://spring.io/[Spring Framework] or the https://micronaut.io/[Micronaut framework]) to their specific repositories.
+This repository should be used for reporting issues related specifically to the Maven or Gradle plugins for GraalVM Native Image.
+For issues related to frameworks such as https://spring.io/[Spring Framework] or https://micronaut.io/[Micronaut framework], please report them to their respective repositories.