* classloader by {@link JApiCmpWorkerAction}, so there is no way to use a
     * normal property on the renderer instance and just set the location of the API file in it.
     *
     * Instead, we'll encode the path to the file in the description data field, as a link.  This is
     * useful regardless of this renderer's needs, since now there will be a link embedded in the report

        then:
        format(result.docbook) == '''<orderedlist><listitem>item1</listitem></orderedlist>'''
    }

    def convertsALinkTag() {
        _ * classMetaData.rawCommentText >> '{@link someClass} {@link otherClass#method(a, b) label}'

        when:
        def result = parser.parse(classMetaData, listener)

        then:
        format(result.docbook) == '''<para><xref/> <xref/></para>'''

            <tr>
                <td>
                    <literal><link linkend="method1Id">methodName</link>()</literal>
                </td>
                <td>
                    <para>method description</para>
                </td>
            </tr>
            <tr>
                <td>
                    <literal><link linkend="method2Id">methodName</link>(p)</literal>
                </td>
                <td>

import org.w3c.dom.Document
import org.w3c.dom.Element
/**
 * Generates the docbook source for the DSL reference guide.
 *
 * Uses the following as input:
 * <ul>
 * <li>Meta-data extracted from the source by {@link gradlebuild.docs.dsl.source.ExtractDslMetaDataTask}.</li>
 * <li>Meta-data about the plugins, in the form of an XML file.</li>

 *
 * Takes the following as input:
 * <ul>
 * <li>A source docbook XML file.</li>
 * <li>Meta-info about the canonical documentation for each class referenced in the document, as produced by {@link gradlebuild.docs.dsl.docbook.AssembleDslDocTask}.</li>
 * </ul>
 *
 */
@CacheableTask
abstract class UserGuideTransformTask extends DefaultTask {

    @PathSensitive(PathSensitivity.NONE)
    @InputFile

    def ignoresWhitespaceAndEOLCharsBetweenJavadocTagNameAndValue() {
        when:
        lexer.pushText("* {@link\n *  Something}")
        lexer.visit(visitor)

        then:
        1 * visitor.onStartJavadocTag('link')
        1 * visitor.onText('Something')
        1 * visitor.onEndJavadocTag('link')
        1 * visitor.onEnd()
        0 * visitor._
    }

    def ignoresBadlyFormedHtmlElement() {

    def rendersLinkToApiClass() {
        when:
        def link = renderer.link(type('org.gradle.SomeClass'), listener)

        then:
        format(link) == '<apilink class="org.gradle.SomeClass"/>'
        _ * model.isKnownType('org.gradle.SomeClass') >> true
    }

    def rendersLinkToApiClassArray() {
        when:
        def link = renderer.link(type('org.gradle.SomeClass', true), listener)

        then:

        def link = converter.resolve('org.gradle.SomeClass', classMetaData, listener)

        then:
        format(link) == '''<UNHANDLED-LINK>org.gradle.SomeClass</UNHANDLED-LINK>'''
    }

    def convertsClassAndMethodNameToLink() {
        ClassMetaData targetClass = Mock()
        MethodMetaData method = method('someName')
        _ * nameResolver.resolve('SomeClass', classMetaData) >> 'org.gradle.SomeClass'

        given:
        sampleDoc << """
=== Valid Javadoc Links

Be sure to see: `@link:{javadocPath}/org/gradle/api/tasks/InputDirectory.html[InputDirectory]`

import org.gradle.api.tasks.TaskAction

/**
 * Extracts meta-data from the Groovy and Java source files which make up the Gradle API. Persists the meta-data to a file
 * for later use in generating documentation for the DSL, such as by {@link gradlebuild.docs.dsl.docbook.AssembleDslDocTask}.
 */
@CacheableTask
abstract class ExtractDslMetaDataTask extends SourceTask {
    @OutputFile
    abstract RegularFileProperty getDestinationFile();

    /**