diff --git a/docs/tools/ikvmc.md b/docs/tools/ikvmc.md
index 4107d2a563..c27db5711d 100644
--- a/docs/tools/ikvmc.md
+++ b/docs/tools/ikvmc.md
@@ -1,6 +1,8 @@
# ikvmc Tool
-The `ikvmc` tool converts Java bytecode to .NET dll's and exe's.
+> The `ikvmc` tool is considered an advanced option and it is recommended that new projects use the `IkvmReference` for the .NET SDK for most use cases.
+
+The `ikvmc` tool converts Java bytecode to .NET DLL and EXE files.
- [Usage](#usage)
- [Options](#options)
@@ -27,50 +29,87 @@ Name of a Java `.class` or `.jar file`. May contain wildcards (`*.class`).
## Options
-| Source | Description |
+### Command Help
+
+| Source | Description |
|---|---|
| `-?\|-help` | Displays command syntax and options for the tool. |
-| `@` | Read more options from the provided file. |
+
+### Output Files
+
+| Source | Description |
+|---|---|
| `-out:` | Specifies the name of the `outputfile`. Should have a .dll extension (if -target is library) or an .exe extension (if -target is exe or winexe). In most cases, if you omit this option, `ikvmc` will choose an output name based on the -target and the name of the input files. However, if you specify input files using wildcards, you must use this option to specify the output file. |
| `-assembly:` | Specifies the name of the generated assembly. If omitted, the assembly name is (usually) the output filename. |
+| `-version:` | Specifies the output assembly version. |
+| `-fileversion:` | Specifies the output assembly file version. |
| `-target:` | Specifies whether to generate an .exe or .dll. `target-type` is one of - `exe` - generates an executable that runs in a Windows command window
- `winexe` - generates an .exe for GUI applications
- `library` - generates a .dll
- `module` - generates a .netmodule
On Linux, there is no difference between exe and winexe. |
| `-platform:` | Limit which platforms this code can run on:- `x86` - 32 bit
- `Itanium`
- `x64`
- `anycpu`
The default is `anycpu`. This can be helpful if your Java code use a dll via JNI. For example a 32 bit dll should also run on a 64 bit system as 32 bit application. |
| `-keyfile:` | Uses `keyfilename` to sign the resulting assembly. |
| `-key` | Use `keycontainer` to sign the assembly. |
| `-delaysign` | Delay-sign the assembly. |
-| `-version:` | Specifies the output assembly version. |
-| `-fileversion:` | Specifies the output assembly file version. |
-| `-main:` | Specifies the name of the class containing the main method. If omitted and the -target is exe or winexe, ikvmc searches for a qualifying main method and reports if it finds one. |
-| `-r:\|-reference:` | If your Java code uses .NET API's, specify the dll's using this option. This option can appear more than once if more than one library is referenced. Wildcards are permitted (e.g. `C:\libs\*.dll`). |
-| `-recurse:` | Processes all files matching `filespec` in and under the directory specified by filespec. Example: `-recurse:*.class` |
-| `-nojni` | Do not generate JNI stub for native methods. |
-| `-resource:=` | Includes path as a Java resource named `name`. |
-| `-externalresource:=` | Reference file as Java resource. |
+
+### Input Files
+
+
+| Source | Description |
+|---|---|
+| `-r:\|-reference:` | Add a reference to a class library DLL (.NET assembly). When building Java projects (`.jar` or `.class` files), this can be used to add dependent projects that had previously been compiled. The dependency must be compiled first. This option can appear more than once to reference multiple libraries. |
+| `-recurse:` | Processes all files matching `filespec` in and under the directory specified by `filespec`. Example: `-recurse:*.class` |
+| `-exclude:` | `filename` is a file containing a list of classes to exclude. |
+
+### Resources
+
+| Source | Description |
+|---|---|
| `-win32icon:` | Embed specified icon in output. |
| `-win32manifest:` | Specify a Win32 manifest file (.xml). |
+| `-resource:=` | Includes path as a Java resource named `name`. |
+| `-externalresource:=` | Reference file as Java resource. |
| `-compressresources` | Compress resources. |
-| `-exclude:` | `filename` is a file containing a list of classes to exclude. |
-| `-debug` | Generates debugging information in the output. Note that this is only helpful if the `.class` files contain debug information (compiled with the `javac -g` option). |
-| `-srcpath:` | Specifies the location of source code. Use with `-debug`. The package of the class is appended to the specified `path` to locate the source code for the class. |
-| `-Xtrace:` | Displays all trace points with `name`. |
-| `-Xmethodtrace:` | Builds method trace into the specified output method. |
+
+### Code Generation
+
+| Source | Description |
+|---|---|
+| `-debug` | Generates debugging information in the output. Note that this is only helpful if the `.class` files contain debug information (compiled with the `javac -g` option). This option also produces somewhat less efficient CIL code. |
| `-noautoserialization` | Disable automatic .NET serialization support. |
| `-noglobbing` | Don't glob the arguments passed to `-main`. |
| `-nojni` | Do not generate JNI stub for native methods. |
| `-opt:fields` | Remove unused private fields. |
| `-removeassertions` | Remove all assert statements. |
| `-strictfinalfieldsemantics` | Don't allow final fields to be modified outside of initializer methods. |
+
+### Errors and Warnings
+
+| Source | Description |
+|---|---|
| `-nowarn:` | Suppress specified warnings. |
| `-warnaserror` | Treat all warnings as errors. |
| `-warnaserror:` | Treat specified warnings as errors. |
| `-writeSuppressWarningsFile:` | Write response file with `-nowarn:` options to suppress all encountered warnings. |
+
+
+### Miscellaneous
+
+| Source | Description |
+|---|---|
+| `@` | Read more options from the provided file. |
| `-nologo` | Suppress compiler copyright message. |
-| `-srcpath:` | Prepend path and package name to source file. |
+
+### Advanced
+
+| Source | Description |
+|---|---|
+| `-main:` | Specifies the name of the class containing the main method. If omitted and the -target is exe or winexe, ikvmc searches for a qualifying main method and reports if it finds one. |
+| `-srcpath:` | Specifies the location of source code. Use with `-debug`. The package of the class is appended to the specified `path` to locate the source code for the class. |
| `-apartment:` | Apply a thread apartment state attribute to `-main` based on the selected option:- `sta` - Apply `STAThreadAttribute`
- `mta` - Apply `MTAThreadAttribute`
- `none` - Apply no attribute
The default option is `sta`. |
| `-D=` | Set a Java system property (at runtime). |
-| `-ea\|-enableassertions[: [...] \|:]` | Set Java system property to enable assertions. |
-| `-da\|-disableassertions[: [...] \|:]` | Set Java system property to disable assertions. |
+| `-ea\|-enableassertions[:[\|]]` | Set Java system property to enable assertions. A class name or package name can be specified to enable assertions for a specific class or package. |
+| `-da\|-disableassertions[:[\|]]` | Set Java system property to disable assertions. A class name or package name can be specified to disable assertions for a specific class or package. |
| `-nostacktraceinfo` | Don't create metadata to emit rich stack traces. |
+| `-Xtrace:` | Displays all trace points with `name`. |
+| `-Xmethodtrace:` | Builds method trace into the specified output method. |
| `-privatepackage:` | Mark all classes with a package name starting with `prefix` as internal to the assembly. |
| `-publicpackage:` | Mark all classes with a package name starting with `prefix` as public to the assembly. |
| `-time` | Display timing statistics. |
@@ -87,12 +126,13 @@ Name of a Java `.class` or `.jar file`. May contain wildcards (`*.class`).
| `-proxy:` | Undocumented. |
| `-nojarstubs` | Undocumented temporary option to mitigate risk. |
| `-w4` | Undocumented option to compile core class libraries with, to disable MethodParameter attribute. |
-| `-strictfinalfieldsemantics` | Undocumented. |
-| `-remap` | Undocumented. |
+| `-strictfinalfieldsemantics` | Undocumented. For internal use. |
+| `-remap` | Undocumented. For internal use. |
+| `-runtime` | Specifies the `IKVM.Runtime.dll` library to use. Not fully functional. |
## Notes
-The ikvmc tool generates .NET assemblies from Java class files and jar files. It converts the Java bytecode in the input files to .NET CIL. Use it to produce
+The `ikvmc` tool generates .NET assemblies from Java class files and jar files. It converts the Java bytecode in the input files to .NET CIL. Use it to produce
- .NET executables (`-target:exe` or `-target:winexe`)
- .NET libraries (`-target:library`)