Extend Dokka support

[tripolkaandrey]

Preface

This PR extends Dokka support for our projects. It should give an option of a smooth migration from Javadoc to Dokka documentation generation. The reason behind this is the better UI/UX of the tool output. A side-by-side comparison of the existing UI(Javadoc) vs the new one can be made by visiting the links below:

• Old
• New

What's new?

Dokka documentation as a publish artifact

A new option was added to include dokkaJar as an artifact. By default, this option is set to false. The artifact can be included using the following setup:

spinePublishing {
    dokkaJar {
        enabled = true
    }
}

Use Dokka in Java projects

A new script plugin was created to ease adding Dokka to a Java project.

Firstly, The plugin configures Dokka for a Java project. As Dokka is initially developed for Kotlin projects, without the proper setup, it "sees Java code as Kotlin one"(for example, the documentation for method void demo() becomes
fun demo()). More information can be found here.

Secondly, it keeps sure that things annotated with @Internal are not present in the resulting documentation. This is done by using the custom Dokka plugin from dokka-extensions.

Lastly, things this plugin also takes care of:

• setting the output directory for this tool as "buildDirectory/docs/dokka";
• configuring styles and logo to be coherent with Spine theme.
• skipping empty packages;
• displaying inherited members for a type in a separate tab.

How created functionality can be used:

subprojects {
  apply {
      plugin("dokka-for-java")
  }
}

Important details

Dokka loads many classes (especially for large multi-module projects), relying heavily on the Metaspace. It leads to the OutOfMemory exception on large projects. As suggested by Dokka developers and community you may need to manually set MaxMetaspaceSize in your gradle.properties. This could be done by adding the following line:

org.gradle.jvmargs=-XX:MaxMetaspaceSize=512m

The 1.6.10 version of Dokka deals with Metaspace much better than previous versions, but the exception is still possible. For example, core-java did not raise any exceptions when using Dokka for generating documentation artifacts for every subproject as part of the publish task. Some things that could also be helpful when dealing with the issue:

• kill the existing Gradle daemon and try again;
• use the --no-daemon option when running as a CLI command.

[armiol]

@tripolkaandrey please see my comment.

[armiol]

Let's make this expression syntactically similar to protoJar (see above).

Also, the naming is important. We drop "include" prefix in order to make the whole thing shorter. Imagine if we don't:

spinePublishing {
    // ...

    
    includeTestJar { ... }
    includeProtoJar { ... }
    includeDokkaJar ...
}

Notice how much space this "include" takes? And the person who reads this needs to traverse down to the meaningful part, skipping "include" every time.

[armiol]

LGTM.