skip to content

Beyond saying what's wrong, how does the Problems API let you tell the user how to fix it and where to read more?

level: middleimportance: should knowfreq 22%

answer

  1. solution(String) — repeatable, appends
  2. documentedAt(url) — 'learn more' link
  3. details() = full description, label = headline
  4. actionable diagnostics, not log blobs

basics

~10 s

On the ProblemSpec you call solution("...") to give actionable fix advice (callable multiple times) and documentedAt("https://...") to attach a documentation link. Consumers surface these as suggestions and a 'learn more' link.

solid answer

~50 s

A good diagnostic is actionable, so `ProblemSpec` carries two facets beyond severity and location. **`solution(String)`** adds a concrete remediation hint — e.g. "Set the 'apiUrl' property in build.gradle.kts". You can call it several times to attach multiple alternative fixes; each call appends. **`documentedAt(String url)`** attaches a documentation link so consumers can render a "learn more" affordance pointing at your plugin's docs or a Gradle guide. These pair naturally with `details(String)` (the longer description) and the problem's label (the short headline). The point is that an IDE or the HTML problems report can show a structured: *headline → details → here's how to fix it → read more*, all as typed fields rather than one blob of console text. So when designing diagnostics you generally set: a stable problem id + label, a severity, at least one location, one or more solutions, and a documentedAt link.

code

kotlin · 6 lines
kotlin
reporter.report(problemId) { spec ->
    spec.severity(Severity.ADVICE)
        .details("Task 'foo' has no description")
        .solution("Add task.description = \"...\" so it shows in ./gradlew tasks")
        .documentedAt("https://docs.gradle.org/current/userguide/more_about_tasks.html")
}

go deeper

for a junior

Know solution() gives a fix hint and documentedAt() adds a docs link.

for a middle

Explain solution() is repeatable and how solution/documentedAt/details/severity/location compose into one actionable problem.

for a senior

Argue for typed remediation fields enabling IDE quick-fix-style rendering vs free-text logs.

for a principal

Treat documentedAt + solution as part of a product-quality diagnostics standard plugins should adopt, with stable doc URLs maintained alongside the plugin.

## From 'what' to 'what to do' Reporting that something is wrong is half the job; users want **remediation**. The Problems API models this with dedicated `ProblemSpec` fields so consumers can present fixes distinctly from the description. ## solution(String) `spec.solution("...")` attaches an actionable suggestion. It is **repeatable** — each call appends another solution — so you can offer alternatives: ```kotlin spec.solution("Add an 'apiKey' to gradle.properties") .solution("Or pass -Papi.key=... on the command line") ``` Keep each solution a short imperative the user can act on. Consumers may render them as a bullet list of suggestions. ## documentedAt(String) `spec.documentedAt("https://docs.example.com/plugin/apiKey")` records a documentation URL. IDEs and the HTML report turn this into a "learn more" link. Use it to point at canonical docs rather than cramming a paragraph into `details`. ## How these fields fit together A fully-formed problem typically sets: - **id + label** — `ProblemId.create(id, label, group)`; the short, stable headline. - **details(String)** — a fuller human description. - **severity(Severity)** — ADVICE / WARNING / ERROR. - **location** — `lineInFileLocation(...)` / `fileLocation(...)` / `pluginLocation(...)`. - **solution(String)** — one or more fixes. - **documentedAt(String)** — a docs link. ```kotlin reporter.report(problemId) { spec -> spec.severity(Severity.WARNING) .details("The 'compatibility' value 'JDK8' is deprecated") .lineInFileLocation("build.gradle.kts", 14, 3, 30) .solution("Use 'JDK17' instead") .documentedAt("https://docs.example.com/migrate-jdk17") } ``` ## Why typed fields beat a log string Because solutions and docs links are separate typed fields, an IDE can render a quick-fix-style list and a clickable link, and the HTML problems report can group and display them consistently. Stuffing all of that into `logger.warn` would force every consumer to parse free text — exactly what the Problems API removes.

  • Can you attach more than one solution to a single problem?
    Yes — solution() is repeatable; each call appends another suggestion, so you can offer several alternative fixes.
  • What's the difference between details() and solution()?
    details() is the human description of what's wrong; solution() is the actionable remediation. They're separate typed fields so consumers can present 'what' and 'how to fix' distinctly.

saying these in an interview costs you the question

  • Putting the fix instructions and doc URL inside details() text instead of using solution()/documentedAt().
  • Thinking solution() can only be called once — it appends, so multiple are allowed.

context

resolving links…