Javadoc generation fails via dokka-gradle-plugin (v0.9.9)

[codeprogression]

Given the closure ...

dokka {
    moduleName = 'data'
    outputFormat = 'javadoc'
    outputDirectory = "$buildDir/docs/ktdoc"
    linkMapping {
        dir = "src/main/kotlin"
        url = "https://internal/path/to/repo/src/main/kotlin"
    }
    sourceDirs = files('src/main/kotlin')
}

... Receiving the following output when running ./gradlew dokka:

generation completed successfully
null:-1:-1: Tag @see cannot be used in inline documentation.  It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.
null:-1:-1: Tag @see cannot be used in inline documentation.  It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.
null:-1:-1: Tag @see cannot be used in inline documentation.  It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.
null:-1:-1: Tag @see cannot be used in inline documentation.  It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.
null:-1:-1: Tag @see cannot be used in inline documentation.  It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.
null:-1:-1: Tag @see cannot be used in inline documentation.  It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.
null:-1:-1: Tag @see cannot be used in inline documentation.  It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.
null:-1:-1: Tag @see cannot be used in inline documentation.  It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.
com.sun.tools.doclets.internal.toolkit.util.DocletAbortException: java.lang.StackOverflowError

• I have no @see tags defined
• Not all html files are created (causing broken links). e.g, index.html is never created
• When outputFormat is not specified, default html files are created correctly

Let me know if you need any more information. Thanks!

[yole]

I'd need to see the source file which causes the problem

[codeprogression]

@yole, after further investigation, these are actually two separate error conditions. One is fatal to the javadoc generation, the other isn't.

The stack overflow error is caused if I apply an annotation to an interface:

package demo

/**
 * This class supports greeting people by name.
 *
 * @property name The name of the person to be greeted.
 */
class GreeterImpl(val name: String): Greeter {

    /**
     * Prints the greeting to the standard output.
     */

    override fun greet() {
        println("Hello $name!")
    }

}

/**
 * Implementers will greet people.
 */
@Beta
interface Greeter {
    fun greet()
}

fun main(args: Array<String>) {
    demo.GreeterImpl(args[0]).greet()
}

@Retention(AnnotationRetention.BINARY)
@Target(AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FIELD, AnnotationTarget.FUNCTION,
        AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.CLASS, AnnotationTarget.FILE)
@MustBeDocumented
annotation class Beta

In this case, the documentation halts. Applying an annotation to the interface methods does not cause issues. (The stack overflow does not occur when the output format is "HTML," only "javadoc")

---

The "null tag" error occurs if a referenced class has the @suppress comment added:

package demo

/**
 * This class supports greeting people by name.
 * Inherits from [Greeter] which has a `suppress` doc comment
 *
 * @property name The name of the person to be greeted.
 */
class GreeterImpl(val name: String): Greeter {

    /**
     * Prints the greeting to the standard output.
     */

    override fun greet() {
        println("Hello $name!")
    }

}

/**
 * @suppress
 */
interface Greeter {
    fun greet()
}

fun main(args: Array<String>) {
    demo.GreeterImpl(args[0]).greet()
}

In this case, the documentation completes despite the null:-1:-1: Tag @see messages.

---

If I come up with additional cases, I will let you know. Hope that helps!

[yole]

Thanks for your investigation, it definitely does help! I'll look into these issues soon.

[codeprogression]

@yole This is still happening in 0.9.10. Wondering if it will be worked on soon. Thanks.

[codeprogression]

@semoro @yole Thanks for working on this one!

[xeruf]

I still get spammed to death by null:-1:-1: Tag @see cannot be used in inline documentation. It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method even though I have no @see tag ANYWHERE. And the error message isn't any help either...

[mstachniuk]

Same to me (using version 0.9.17). You can check my project: https://github.com/mstachniuk/graphql-schema-from-introspection-generator
./gradlew clean build

> Task :graphql-schema-from-introspection-generator-core:dokka
null:-1:-1: Tag @see cannot be used in inline documentation.  It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.

[semoro]

Problem with @see tags still reproduces, and should be fixed

[AlexanderLS]

Same to me (using version 0.9.17). You can check my project: https://github.com/Vorlonsoft/AndroidRate

[xeruf]

Guys, this is super annoying! My build log contains over 20 lines of this useless message:
null:-1:-1: Tag @see cannot be used in inline documentation. It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.
it isn't an actionable error, so please just remove it until is serves a purpose...

[JWT007]

Any word on this? Since I tend to use @suppress on overridden hashCode/equals methods my build log if full of the null errors ... is it just a simple mixup confusing @suppress with @see???

[JWT007]

So its not just the @suppress.

It is also caused by the documentation links A [FooBar] implementation. ... this gets resolved as a @see.

Removing the link references for a class/method eliminates the error.

[mdashlw]

Still relevant for me, I have no @see in my docs at all
Using dokka maven plugin, 0.9.18

[AmrAfifiy]

Seeing the same problem, happens when an interface B implements an interface A, with A having an annotation.

[pavelaizen]

Can we remove this logs from the console output?

[kamildoleglo]

This will be fixed in 0.11.0 hopefully

[ccampo133]

Running into this as well. Happens when you reference classes/functions using brackets, e.g.

/**
 * See [foo] and [bar]
 */

Output spams:
null:-1:-1: Tag @see cannot be used in inline documentation. It can only be used in the following types of documentation: overview, package, class/interface, constructor, field, method.

[Kordyjan]

As far as I know, it is fixed in 1.4.0. If the problem is persisting it is ok to open a new issue as it will definitely have a different root cause that this problem.