From 09914251fe77104ad0250d39f6f3fa127c4d7221 Mon Sep 17 00:00:00 2001 From: Alex Semin Date: Fri, 1 Dec 2023 14:23:19 +0100 Subject: [PATCH] Add missing javadocs and since-annotation to Problems API members --- .../api/problems/BasicProblemBuilder.java | 1 + .../problems/ReportableProblemBuilder.java | 1 + .../events/problems/AdditionalData.java | 7 +++++++ .../tooling/events/problems/Details.java | 1 + .../events/problems/DocumentationLink.java | 5 +++++ .../events/problems/ExceptionContainer.java | 5 +++++ .../tooling/events/problems/FileLocation.java | 20 ++++++++++++++++++ .../gradle/tooling/events/problems/Label.java | 1 + .../events/problems/PluginIdLocation.java | 5 +++++ .../events/problems/ProblemCategory.java | 3 +++ .../tooling/events/problems/Severity.java | 21 ++++++++++++++++++- .../tooling/events/problems/Solution.java | 6 ++++++ .../events/problems/TaskPathLocation.java | 6 ++++++ 13 files changed, 81 insertions(+), 1 deletion(-) diff --git a/platforms/ide/problems-api/src/main/java/org/gradle/api/problems/BasicProblemBuilder.java b/platforms/ide/problems-api/src/main/java/org/gradle/api/problems/BasicProblemBuilder.java index a8f256ba266..d625eac2a5c 100644 --- a/platforms/ide/problems-api/src/main/java/org/gradle/api/problems/BasicProblemBuilder.java +++ b/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(); } diff --git a/platforms/ide/problems-api/src/main/java/org/gradle/api/problems/ReportableProblemBuilder.java b/platforms/ide/problems-api/src/main/java/org/gradle/api/problems/ReportableProblemBuilder.java index 33d5c58ff73..41342cd22f5 100644 --- a/platforms/ide/problems-api/src/main/java/org/gradle/api/problems/ReportableProblemBuilder.java +++ b/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(); } diff --git a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/AdditionalData.java b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/AdditionalData.java index 3441b081c4a..74d9f26e977 100644 --- a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/AdditionalData.java +++ b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/AdditionalData.java @@ -25,10 +25,17 @@ * Additional data attached to the problem. *

* 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 getAsMap(); } diff --git a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Details.java b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Details.java index a4dcb19e3a9..e7dd18b0107 100644 --- a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Details.java +++ b/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(); diff --git a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/DocumentationLink.java b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/DocumentationLink.java index f3e90d5a9ce..16bbef2c394 100644 --- a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/DocumentationLink.java +++ b/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(); } diff --git a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/ExceptionContainer.java b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/ExceptionContainer.java index 8c21e016939..60b96f1f7bc 100644 --- a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/ExceptionContainer.java +++ b/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(); } diff --git a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/FileLocation.java b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/FileLocation.java index ef55988932c..4eb69757ee7 100644 --- a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/FileLocation.java +++ b/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(); } diff --git a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Label.java b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Label.java index 5142f4ebbbf..6c50ac1259d 100644 --- a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Label.java +++ b/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(); } diff --git a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/PluginIdLocation.java b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/PluginIdLocation.java index 0277b85bc7e..abc05496a55 100644 --- a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/PluginIdLocation.java +++ b/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(); } diff --git a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/ProblemCategory.java b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/ProblemCategory.java index 7370e2b232e..9a2dc421dc6 100644 --- a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/ProblemCategory.java +++ b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/ProblemCategory.java @@ -40,6 +40,7 @@ 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(); @@ -47,6 +48,7 @@ public interface ProblemCategory { * The main problem category. * * @return The category string. + * @since 8.6 */ String getCategory(); @@ -54,6 +56,7 @@ public interface ProblemCategory { * The problem's subcategories. * * @return the subcategories. + * @since 8.6 */ List getSubCategories(); } diff --git a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Severity.java b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Severity.java index ff228c9f332..68266267185 100644 --- a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Severity.java +++ b/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(); } diff --git a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Solution.java b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Solution.java index 7478ce15409..5cb25f8c683 100644 --- a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/Solution.java +++ b/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(); } diff --git a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/TaskPathLocation.java b/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/TaskPathLocation.java index c36fa4ac3a4..561c4178018 100644 --- a/platforms/ide/tooling-api/src/main/java/org/gradle/tooling/events/problems/TaskPathLocation.java +++ b/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(); }