Add full documentation to the reference.conf file

core/driver/sources/src/main/resources/reference.conf

@@ -5,12 +5,49 @@ probe {
 
   // `intellij` is for org.virtuslab.ideprobe.config.IntellijConfig - default values below:
   intellij {
+    // `plugins` array contains IntelliJ plugins which should be installed and enabled on IntelliJ run. Here you can add
+    // your IntelliJ plugin for tests (amongst other plugins). There are a few ways to provide a proper entry pointing
+    // to a plugin:
+    // 1. By using a direct URI pointing to the plugin (could be from a website or from a local file). For example:
+    #     { uri = https://packages.jetbrains.team/maven/p/ij/intellij-dependencies/com/intellij/remoterobot/robot-server-plugin/0.11.15/robot-server-plugin/0.11.15.zip }
+    // 2. By using default IntelliJ plugins repository (see `probe.resolvers.plugins.repository.uri`) with additional
+    //    id (pluginId), version and (optional) channel parameters which is translated into a URL with a query string.
+    //    For example:
+    #       { id = "org.intellij.scala", version = "2020.3.369", channel = "nightly" }
+    //      will be resolved into following URL with query string (from where ide-probe should download the plugin):
+    //      https://plugins.jetbrains.com/plugin/download?pluginId=org.intellij.scala&version=2020.3.369&channel=nightly
+    //    and without the optional "channel" parameter:
+    #       { id = "org.intellij.scala", version = "2020.3.369" }
+    //      will be resolved into following URL with query string (from where ide-probe should download the plugin):
+    //      https://plugins.jetbrains.com/plugin/download?pluginId=org.intellij.scala&version=2020.3.369
+    // 3. By using a bundled IntelliJ plugin. Such plugin should be bundled in your project as a module/subproject and
+    //    available on the classpath when IntelliJ instance should run. For example - such plugin subproject should be
+    //    built and published to a `target` directory before performing tests (during compilation).
+    //    There are two ways to point to a bundled IntelliJ plugin:
+    //    a) By providing plugin's resource file name (most probably plugin subproject's name followed by version).
+    //       For example:
+    #        { bundle = "driver-test-plugin_2.13-0.45.0-SNAPSHOT.zip" }
+    //       whch will be resolved properly if mentioned .zip file is available on the classpath.
+    //    b) By providing three values realted to the plugin: name, scalaVersion (major) and version. For example:
+    #        { bundle = "driver-test-plugin", scalaVersion = "2.13", version = "0.45.0-SNAPSHOT" }
+    //       which will be resolved the same as the earlier example.
     plugins = []
+
+    // `version.release` is the "Version" and connected `version.build` is the "Build Number" of IntelliJ IDEA version.
+    // You can search for proper string pairs here:
+    // https://www.jetbrains.com/intellij-repository/releases/ under "com.jetbrains.intellij.idea" heading.
+    // Moreover - builds from https://www.jetbrains.com/intellij-repository/snapshots/ can be used by default as well.
+    // If you want to change the default intellij version, provide both parameters in your .conf file.
+    // Notes:
+    // - `version.release` takes precedence over `version.build`. If both values point to two different builds, then
+    //    `version.release`- related build will be used.
+    // - It is allowed to provide only one of two values (build or release). In order to do so, you have to
+    //    do as follows. If you want to specify only the `version.release` string - you can just do it and your version
+    //    will be used. If you want to specify only the `version.build` string - you have to additionally override
+    //    `version.release` and set it to a `null` value. Nevertheless, best if you provide both values that match
+    //    because ide-probe uses `version.release` to choose the version and `version.build` number
+    //    for naming cache directories etc.
     version {
-      // `release` is the "Version" and connected `build` is the "Build Number" of IntelliJ IDEA version. Both should
-      // be provided and they should match. You can search for proper string pairs here:
-      // https://www.jetbrains.com/intellij-repository/releases/ under "com.jetbrains.intellij.idea" heading.
-      // If you want to change the default intellij version, provide both parameters in your .conf file.
       build = "212.5080.55"
       release = "2021.2.1"
 
@@ -161,34 +198,106 @@ probe {
       "https://cache-redirector.jetbrains.com/intellij-jbr/jbr-[major]-[platform]-x64-b[minor].tar.gz"
     ]
 
+    // The maximal number of retries that should be performed by resolvers when resolving a pattern to a resource.
     retries = 0
   }
 
   // `driver` is for `org.virtuslab.ideprobe.config.DriverConfig` - default values below
   driver {
+
+    // `driver.launch` contains settings that define how IDE should be started.
     launch {
+
+      // `driver.launch.command` is the command used to launch the IDE. By default, the driver uses the `idea` command,
+      // but user can specify a custom command. Note, that the `idea` is available on the PATH,
+      // if the user wants to wrap it in some custom logic.
       command = []
+
+      // `driver.launch.timeout` is the maximum time the driver will wait for the IDE to connect the probe.
+      // After exceeding this time, the whole test fails. Note: format for `timeout` should be compatible with
+      // possible formats for `scala.concurrent.duration.Duration`.
       timeout = "30.seconds"
     }
+
+    // `driver.check` defines how ide-probe should react to IDE errors and freezes. By defeault, the driver doesn't
+    // fail the test upon detecting any errors or freezes during the execution. This behavior can be chenged here.
     check {
+
+      // `driver.check.errors` defines how ide-probe should react to IDE errors.
       errors {
+
+        // `driver.check.errors.enabled` decides if ide-probe should throw an exception (and in result - fail the test)
+        // if IDE errors have been detected. By default, it is disabled. Set to `true` to enable this functionality.
         enabled = false
+
+        // `driver.check.errors.includeMessages` defines which IDE error messages should make ide-probe throw an exception
+        // and fail the test. By default, `includeMessages` contains one regular expression, that matches
+        // all IDE errors messages. So, any IDE error will make the test fail if `driver.check.errors.enabled`
+        // is set to `true`. If you want to include only a subset of errors whose substrings match certain
+        // `includeMessages` entries, you have to put them into this field.
+        //
+        // `driver.check.errors.excludeMessages` defines which IDE error messages should NOT make ide-probe
+        // throw an exception and fail the test. In other words, here you can define, which IDE errors
+        // should be ignored even if `driver.check.errors.enabled` is set to `true`.
+        //
+        // Both for `includeMessages` and for `excludeMessages` you can define an entry in one of two possible ways:
+        // 1. By using a regex-based string. For example: ".*at com.intellij.uast.UastMetaLanguage.*" will match
+        //    any error message that contains "at com.intellij.uast.UastMetaLanguage". Note: your regex-based string
+        //    CAN NOT be a multi-line string.
+        // 2. By using a raw string without regular expressions. In such case ide-probe just checks if IDE error message
+        //    contains your raw string. The benefit of this option is that you can use a multi-line string (part of
+        //    stacktrace). You don't have to worry about line indentations here as each line is trimmed before performing
+        //    the check. If you want to use a multi-line stirng, use triple quotes: """<your multi-line string...>""".
+        //
+        // If an IDE error matches both an entry from `includeMessages` and another entry from `excludeMessages`,
+        // then such IDE error will be ignored (`excludeMessages` takes precedence).
         includeMessages = [".*"]
         excludeMessages = []
       }
+
+      // `driver.check.freezes.enabled` defines if ide-probe should throw an exception and fail the test if IDE freezes
+      // have occured during test. By default, this functionality is disabled. Set to `true` to enable.
       freezes.enabled = false
     }
+
+    // `driver.display` defines the display mode which should be used for the IDE run. By default, it is "native",
+    // which means that everything is displayed on the screen and you can interact with the IDE during test.
+    // Another possible value is "xvfb" which makes the IDE run in the xvfb mode (no display). This config can be set
+    // either with a raw string value or by setting the IDEPROBE_DISPLAY environment variable which overrides the default value.
     display = "native" # OR "xvfb" - these are two possible values
     display = ${?IDEPROBE_DISPLAY}
+
+    // `driver.xvfb` contains parameters that are used if IDE runs in the xvfb mode. Basically, it contains three
+    // screen size parameters that are passed to the "−screen" command line switch of xvfb.
+    // See https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml for more details.
     xvfb {
       screen {
         width = 1920
         height = 1080
         depth = 24
       }
     }
+
+    // `driver.headless` defines if IDE should run in a headless mode (without a graphical user interface). If you want
+    // to use it, set to `true`. Specifically, it adds " headless" to the basic launch command ("idea").
+    // Note: if `headless` is set to `true`, it takes precedence over `driver.display`, which means that
+    // IDE will run in the headless mode (and not in a "native" or "xvfb" mode).
+    // Additionally, unless run in headless mode, the driver captures the screenshots of the screen periodically,
+    // so it can then be exposed on the CI for the user to inspect the IDE state in case of failures. If you run in the
+    // headless mode - then no screenshots will be captured.
     headless = false
+
+    // `driver.vmOptions` are java virtual machine (JVM) options that are used by the driver to further customize the IDE.
+    // Each entry in the `vmOptions` array is a raw string. You can add your configurations for the java virtual machine,
+    // like "-Xmx4096m" or "-XX:ReservedCodeCacheSize=240m". These entries are saved by ide-probe into the
+    // `IDE_HOME/bin/ideprobe.vmoptions` file (one entry per line) which is later on used by IntelliJ to configure JVM.
+    // See https://intellij-support.jetbrains.com/hc/en-us/articles/206544869-Configuring-JVM-options-and-platform-properties
+    // for more details.
     vmOptions = []
+
+    // `driver.env` allows you to add other environment variables that should be available during the IDE run.
+    // `env` is a Map with string keys and string values (Map[String, String]), so you can add entries like this:
+    // { "MY_ENV_VARIABLE" : "some important value" }
     env = {}
   }
 

core/driver/sources/src/main/scala/org/virtuslab/ideprobe/dependencies/IntelliJVersion.scala

@@ -6,8 +6,6 @@ import pureconfig.generic.semiauto.deriveConvert
 import org.virtuslab.ideprobe.IntelliJFixture
 import org.virtuslab.ideprobe.config.IntellijConfig
 
-// the `ext` field (file extension) must be an Option[String] and not a String for the ExistingIntelliJ usage
-// inside the `org.virtuslab.ideprobe.dependencies.IntelliJVersionResolver` object
 final case class IntelliJVersion(build: String, release: Option[String], ext: String) {
   def releaseOrBuild: String = release.getOrElse(build)