skip to content

When reporting a problem, what is the difference between contextualLabel and details, and how do they relate to the ProblemId's displayName?

level: middleimportance: should knowfreq 22%

answer

  1. displayName = stable category name
  2. contextualLabel = per-occurrence short headline
  3. details = long body / explanation
  4. label is scannable summary; details is drill-in
  5. don't duplicate across the three

basics

~20 s

The ProblemId displayName is the fixed category label. contextualLabel is the short, occurrence-specific headline (what's wrong here). details is longer explanatory text expanding on it. The label is the summary line; details is the body.

solid answer

~40 s

Three text slots play distinct roles. The **`ProblemId` displayName** is the *stable* human name of the category (e.g. "Version conflict") — same for every occurrence. The **`contextualLabel`** is the *per-occurrence* one-liner that describes this specific instance (e.g. "Conflict on com.foo:bar: 1.2 vs 1.4"); it's what consumers show as the headline for that report. The **`details`** field is the longer prose — background, why it matters, what's happening — shown when the user drills in (e.g. in the HTML report or an IDE tooltip). The rule of thumb: identity/category text is fixed and lives in the id; the variable headline goes in `contextualLabel`; the verbose explanation goes in `details`. Keep `contextualLabel` short and scannable because it appears in summaries; reserve length for `details`.

code

kotlin · 7 lines
kotlin
val id = ProblemId.create("unused-dep", "Unused dependency", group)
problems.reporter.report(id) { spec ->
    spec.contextualLabel("'commons-lang3' is declared but never used")
        .details("No source reference to commons-lang3 was found in :core; " +
                 "declaring it bloats the classpath and slows resolution.")
        .severity(Severity.ADVICE)
}

go deeper

for a junior

Know contextualLabel is the short headline and details is the longer text.

for a middle

Distinguish all three text slots and place variable vs stable text correctly.

for a senior

Establish conventions so labels stay scannable and details carry actionable context consistently.

for a principal

Standardize the wording style across plugins so consumers render a coherent diagnostics experience.

## Three text slots, three jobs A structured problem has more than one piece of text, and conflating them is a common mistake. ### 1. `ProblemId` displayName — the category name Set once when you build the id: `ProblemId.create("version-conflict", "Version conflict", group)`. It is the **stable, human-readable name of the kind of problem**. It does **not** change between occurrences. Consumers use it to label the group/category. ### 2. `contextualLabel` — this occurrence's headline `spec.contextualLabel("Conflict on com.foo:bar: 1.2 vs 1.4")`. This is the **short, situation-specific** line. It's what the console/HTML report/IDE shows as the headline *for this particular report*. Because it surfaces in summaries, keep it tight and scannable — a sentence, not a paragraph. ### 3. `details` — the long explanation `spec.details("Module com.foo:bar was requested at 1.2 by :app and 1.4 by :lib; conflict resolution selected 1.4...")`. This is the **expanded body** users see when they drill into the problem. Put the *why*, the background, and any nuance here. ## How they compose ```kotlin val id = ProblemId.create("version-conflict", "Version conflict", group) // category problems.reporter.report(id) { spec -> spec.contextualLabel("Conflict on com.foo:bar: 1.2 vs 1.4") // headline .details("Requested 1.2 by :app and 1.4 by :lib; resolved to 1.4.") // body .severity(Severity.WARNING) } ``` Reading top to bottom a consumer can render: **category** (Version conflict) → **headline** (Conflict on com.foo:bar...) → **body** (the full explanation). ## Guidance - Don't repeat the displayName inside contextualLabel — it's redundant. - Don't stuff the full explanation into contextualLabel; that's what details is for. - Don't put variable text into the id displayName; that breaks stability and grouping.

  • Where does the variable, occurrence-specific text go?
    In contextualLabel (short headline) and details (long body), plus the location — never in the ProblemId displayName, which must stay stable per category.
  • Why keep contextualLabel short?
    It appears as the headline in console summaries and lists, so it must be scannable. Long explanations belong in details, shown on drill-in.

saying these in an interview costs you the question

  • Putting the full multi-line explanation into contextualLabel.
  • Embedding occurrence-specific text into the ProblemId displayName.

context

resolving links…