Use Dokka instead of Javadoc

[tripolkaandrey]

This PR changes the tool which we use for generating a documentation artifact. Currently, we are using Javadoc. The PR switches it to Dokka. The reason behind this is the better UI/UX of the tool output. Side-by-side comparison of existing UI(Javadoc) vs the new one can be made by visiting the links below:

• Old
• New

The list of things that were also done, except changing the generation of Javadoc JAR to Dokka JAR as a publish artifact, is provided below:

• Bumped version of Dokka;
• Refactored Dokka object in io.spine.internal.dependency for better readability and following already established code style for Gradle Plugin dependency object;
• Created script plugin to ease adding new functionality to Java project. This plugin configures the path for documentation and adds the necessary plugin for a Java project. As this tool is initially developed for Kotlin projects, without proper setup it will "see Java code as Kotlin one"(for example, the documentation for method private void demo() becomes fun demo()). More information can be found in this link.

How created functionality can be used:

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

This automatically sets the output folder for this tool as "buildDirectory/docs/dokka" and configures dokka for a Java project.

Important details

Dokka loads many classes (especially for large multi-module projects), so it relies heavily on the Metaspace. It leads to the OutOfMemory exception on large projects. As suggested by Dokka developers and dev community you may need to manually increase 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 there is still a possibility of the exception. For example, core-java did not raise any exceptions when using Dokka for generating documentation artifacts for every subproject as part of publish task. Some things except mentioned above that could 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.

This PR is now on hold because Dokka documentation has a few issues which should be resolved first. The list of open issues can be found below:

• Dokka generates redundant brackets when processing annotations
• Misleading representation of Java Varargs

[armiol]

I would say, it's because "UI/UX of the tool output" is better.

[armiol]

@tripolkaandrey please see my comments.

[armiol]

This is Kotlin, so instead of <code> please use the backticks:

... provides `customStyleSheets` property

[armiol]

Please have an empty line above @see.

[armiol]

Please allow an empty line between the paragraphs.

[armiol]

One thing missing from the configuration is as follows.

In the Javadoc artifact we have at the moment, the types annotated as @Internal are stripped out. According to our definition of @Internal, although these types are public, we don't consider them being a part of the public API.

You should be able to tell it from your own experience by comparing the test output of Dokka for the client module to the version we have online. A lot of types that Dokka has included, are intentionally excluded in the Javadoc version.

In the build-time codebase, it is performed via the special configuration of Javadoc doclet which excludes all @Internal-annotated things from it. See ExcludeInternalDoclet type in the buildSrc.

With Dokka, an approach to achieve the same result seems to be different — as I can tell by reading the Dokka's manual. We should be able to exclude the types by tweaking the Dokka's configuration.

[armiol]

Another thing here is that today we are going to have one more PR merged to config. In its scope, this code has been eliminated (probably, for good).

Once that request is merged, I'd like you to perform a back-merge from the master branch into this feature branch. And adjust your code accordingly. Let's discuss in person any questions you might have.