/*
 * Copyright 2020 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.gradle.jvm.toolchain;

import org.gradle.api.Describable;
import org.gradle.api.provider.Property;
import org.gradle.internal.HasInternalProtocol;

/**
 * Requirements for selecting a Java toolchain.
 * <p>
 * A toolchain is a JRE/JDK used by the tasks of a build. Tasks of a build may require one or more of the tools javac, java, or javadoc) of a toolchain.
 * Depending on the needs of a build, only toolchains matching specific characteristics can be used to run a build or a specific task of a build.
 *
 * @since 6.7
 */
@HasInternalProtocol
public interface JavaToolchainSpec extends Describable {

    /**
     * The exact version of the Java language that the toolchain is required to support.
     */
    Property<JavaLanguageVersion> getLanguageVersion();

    /**
     * The vendor of the toolchain.
     * <p>By default, toolchains from any vendor are eligible.</p>
     *
     * @since 6.8
     */
    Property<JvmVendorSpec> getVendor();

    /**
     * The virtual machine implementation of the toolchain.
     * <p>By default, any implementation (hotspot, j9, ...) is eligible.</p>
     *
     * @since 6.8
     */
    Property<JvmImplementation> getImplementation();

}

@@ -890,26 +890,18 @@
 ild.
+%0A *
  Tasks 
-of a build 
 may 
@@ -933,16 +933,17 @@
 e tools 
+(
 javac, j
@@ -1121,16 +1121,850 @@
  build.%0A
+ * %3Cp%3E%0A * Even though specification properties can be configured independently,%0A * the configuration must follow certain rules in order to form a  specification.%0A * %3Cp%3E%0A * A %7B@code JavaToolchainSpec%7D is considered %3Cem%3Evalid%3C/em%3E in two cases:%0A * %3Cul%3E%0A * %3Cli%3E when no properties have been set, i.e. the specification is %3Cem%3Eempty%3C/em%3E;%0A * %3Cli%3E when %7B@link #getLanguageVersion() language version%7D has been set, optionally followed by setting any other property.%0A * %3C/ul%3E%0A * %3Cp%3E%0A * In other words, if a vendor or an implementation are specified, they must be accompanied by the language version.%0A * An empty specification in most cases corresponds to the toolchain that runs the current build.%0A * %3Cp%3E%0A * Usage of %3Cem%3Einvalid%3C/em%3E instances of %7B@code JavaToolchainSpec%7D is deprecated and will be removed in the future versions of Gradle.%0A
  *%0A * @s
@@ -2263,32 +2263,40 @@
 hain.%0A     * %3Cp%3E
+%0A     * 
 By default, tool
@@ -2323,36 +2323,171 @@
 or are eligible.
-%3C/p%3E
+%0A     * %3Cp%3E%0A     * Note that the vendor can only be configured if the %7B@link #getLanguageVersion() language version%7D is configured as well.
 %0A     *%0A     * @
@@ -2624,16 +2624,24 @@
    * %3Cp%3E
+%0A     * 
 By defau
@@ -2698,12 +2698,155 @@
 ble.
-%3C/p%3E
+%0A     * %3Cp%3E%0A     * Note that the implementation can only be configured if the %7B@link #getLanguageVersion() language version%7D is configured as well.
 %0A   

Add explanation of invalid toolchain spec to the javadoc