}

    @Override
    public InternalProblemBuilder details(String details) {
        this.details = details;
        return this;
    }

    @Override
    public InternalProblemBuilder documentedAt(@Nullable DocLink doc) {
        this.docLink = doc;
        return this;
    }

    @Override
    public InternalProblemBuilder id(String name, String displayName) {

                .id(TextUtil.screamingSnakeToKebabCase(VALUE_NOT_SET), "Value not set", GradleCoreProblemGroup.validation().property())
                .contextualLabel("doesn't have a configured value")
                .documentedAt(userManual("validation_problems", VALUE_NOT_SET.toLowerCase()))
                .severity(Severity.ERROR)
                .details("This property isn't marked as optional and no value has been configured");

                    .contextualLabel(String.format("has @ServiceReference annotation used on property of type '%s' which is not a build service implementation", typeVariables.get(0).getName()))
                    .documentedAt(userManual("validation_problems", SERVICE_REFERENCE_MUST_BE_A_BUILD_SERVICE.toLowerCase(Locale.ROOT)))
                    .severity(Severity.ERROR)

        problems.size() == 0

        where:
        detailsConfig              | expectedDetails | documentationConfig                         | expecteDocumentation
        '.details("long message")' | "long message"  | '.documentedAt("https://docs.example.org")' | 'https://docs.example.org'
        ''                         | null            | ''                                          | null
    }

     * @return this
     * @since 8.8
     */
    ProblemSpec contextualLabel(String contextualLabel);

    /**
     * Declares where this problem is documented.
     *
     * @return this
     * @since 8.6
     */
    ProblemSpec documentedAt(String url);

    /**
     * Declares that this problem is in a file.
     *
     * @param path the file location
     * @return this
     * @since 8.6
     */

        given:
        def problem = problemReporter.create {
            it.id("id", "label", GradleCoreProblemGroup.validation())
                .documentedAt(new TestDocLink())
                .lineInFileLocation("location", 1, 1)
        }

        when:
        def json = gson.toJson([problem])

        given:
        withReportProblemTask """
            problems.forNamespace('org.example.plugin').reporting {
                it.id('type', 'label')
                .documentedAt("https://example.org/doc")
            }
        """

        when:
        run('reportProblem')

        then:
        receivedProblem.definition.documentationLink.url == 'https://example.org/doc'

                        .documentedAt(userManual("validation_problems", "cacheable_transform_cant_use_absolute_sensitivity"))
                        .contextualLabel("is declared to be sensitive to absolute paths")
                        .severity(ERROR)

        }.also { internalReporter.report(it) }
    }

    private
    fun ProblemSpec.documentOfProblem(problem: PropertyProblem) {
        problem.documentationSection?.let {
            documentedAt(Documentation.userManual("configuration_cache", it.anchor).toString())
        }
    }

    private
    fun ProblemSpec.locationOfProblem(problem: PropertyProblem) {
        val trace = problem.trace.buildLogic()

                            .contextualLabel("must be annotated either with " + cacheableAnnotation + " or with " + disableCachingAnnotation)
                            .documentedAt(userManual("validation_problems", "disable_caching_by_default"))
                            .severity(WARNING)