chore: merge upstream branch gradle/master into main

This commit synchronizes the latest 2 changes from the https://github.com/gradle/gradle/tree/master. The changes include:

4140757: gradle/gradle#27243 Add javadocs and since-annotation to Problems API members
0991425: Add missing javadocs and since-annotation to Problems API members

platforms/ide/problems-api/src/main/java/org/gradle/api/problems/BasicProblemBuilder.java

@@ -42,6 +42,7 @@ public interface BasicProblemBuilder extends ProblemBuilder {
      * Creates the new problem. Calling {@link #build()} won't report the problem via build operations, it can be done separately by calling {@link ReportableProblem#report()}.
      *
      * @return the new problem
+     * @since 8.6
      */
     Problem build();
 }

platforms/ide/problems-api/src/main/java/org/gradle/api/problems/ReportableProblemBuilder.java

@@ -42,6 +42,7 @@ public interface ReportableProblemBuilder extends BasicProblemBuilder {
      * Creates the new problem. Calling {@link #build()} won't report the problem via build operations, it can be done separately by calling {@link ReportableProblem#report()}.
      *
      * @return the new problem
+     * @since 8.6
      */
     ReportableProblem build();
 }

platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/AdditionalData.java

@@ -25,10 +25,17 @@
  * Additional data attached to the problem.
  * <p>
  * The only supported value type is {@link String}.
+ *
  * @since 8.6
  */
 @Incubating
 @NonNullApi
 public interface AdditionalData {
+
+    /**
+     * Returns additional data as a map.
+     *
+     * @since 8.6
+     */
     Map<String, Object> getAsMap();
 }

platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Details.java

@@ -32,6 +32,7 @@ public interface Details {
      * Returns a detailed description of a problem.
      *
      * @return the problem details
+     * @since 8.6
      */
     @Nullable
     String getDetails();

platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/DocumentationLink.java

@@ -28,6 +28,11 @@
 @Incubating
 public interface DocumentationLink {
 
+    /**
+     * Documentation link as a URL.
+     *
+     * @since 8.6
+     */
     @Nullable
     String getUrl();
 }

platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/ExceptionContainer.java

@@ -28,6 +28,11 @@
 @Incubating
 public interface ExceptionContainer {
 
+    /**
+     * Exception that caused the problem.
+     *
+     * @since 8.6
+     */
     @Nullable
     RuntimeException getException();
 }

platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/FileLocation.java

@@ -28,14 +28,34 @@
 @Incubating
 public interface FileLocation extends Location {
 
+    /**
+     * File path.
+     *
+     * @since 8.6
+     */
     String getPath();
 
+    /**
+     * An index of the line in the file, if available.
+     *
+     * @since 8.6
+     */
     @Nullable
     Integer getLine();
 
+    /**
+     * An index of the column in the file, if available.
+     *
+     * @since 8.6
+     */
     @Nullable
     Integer getColumn();
 
+    /**
+     * The length of the region in the file, if available.
+     *
+     * @since 8.6
+     */
     @Nullable
     Integer getLength();
 }

platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Label.java

@@ -30,6 +30,7 @@ public interface Label {
      * Returns the brief description of a problem.
      *
      * @return the label
+     * @since 8.6
      */
     String getLabel();
 }

platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/PluginIdLocation.java

@@ -26,5 +26,10 @@
 @Incubating
 public interface PluginIdLocation extends Location {
 
+    /**
+     * The ID of the plugin to which the location belongs.
+     *
+     * @since 8.6
+     */
     String getPluginId();
 }

platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/ProblemCategory.java

@@ -40,20 +40,23 @@ public interface ProblemCategory {
      * Returns the namespace. Describes the component reporting the problem (Gradle core or plugin ID).
      *
      * @return the problem's namespace.
+     * @since 8.6
      */
     String getNamespace();
 
     /**
      * The main problem category.
      *
      * @return The category string.
+     * @since 8.6
      */
     String getCategory();
 
     /**
      * The problem's subcategories.
      *
      * @return the subcategories.
+     * @since 8.6
      */
     List<String> getSubCategories();
 }

platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Severity.java

@@ -28,21 +28,40 @@
 public interface Severity {
 
     // Note: the static fields must be in sync with entries from org.gradle.api.problems.Severity.
+    /**
+     * Advice-level severity.
+     *
+     * @since 8.6
+     */
     Severity ADVICE = new DefaultSeverity(0, true);
+
+    /**
+     * Warning-level severity.
+     *
+     * @since 8.6
+     */
     Severity WARNING = new DefaultSeverity(1, true);
+
+    /**
+     * Error-level severity.
+     *
+     * @since 8.6
+     */
     Severity ERROR = new DefaultSeverity(2, true);
 
     /**
      * The severity level represented by a string.
      *
      * @return the severity
+     * @since 8.6
      */
     int getSeverity();
 
     /**
-     * returns true if this severity is one of {@link #ADVICE}, {@link #WARNING}, or {@link #ERROR}.
+     * Returns true if this severity is one of {@link #ADVICE}, {@link #WARNING}, or {@link #ERROR}.
      *
      * @return if this instance is a known severity
+     * @since 8.6
      */
     boolean isKnown();
 }

platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Solution.java

@@ -25,5 +25,11 @@
  */
 @Incubating
 public interface Solution {
+
+    /**
+     * A description of a possible solution the user can try to fix the problem.
+     *
+     * @since 8.6
+     */
     String getSolution();
 }

platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/TaskPathLocation.java

@@ -25,5 +25,11 @@
  */
 @Incubating
 public interface TaskPathLocation extends Location {
+
+    /**
+     * Returns the path of this task within the build tree. This is a unique name for this task within the composite build.
+     *
+     * @since 8.6
+     */
     String getIdentityPath();
 }