Javalin: There doesn't seem to be any javadoc for context

[nnathan]

I can't seem to find any javadoc for io.javalin.http.Context: see https://static.javadoc.io/io.javalin/javalin/3.0.0.RC3/io/javalin/http/Handler.html . Is this deliberately omitted or can't be generated from kotlin?

[tipsy]

Hm, I thought they would be generated, all the methods are documented.

[ronMori]

i'll give it a look - just to be clear, the goal is javadoc for both java & kotlin classes.

[tipsy]

Yes. Java should already be working. Looks like everything is present: https://javadoc.io/doc/io.javalin/javalin/3.0.0

All Kotlin files seem to be missing.

[nixxcode]

Hi there, I have been looking into this as a possible first contribution. I have made a few relevant findings.

The Javadoc built-in doc generator doesn't support Kotlin, so a plugin must be used to generate documentation for Kotlin classes. I can see that Dokka 0.9.17 is included in pom.xml, so I tried doing the following:

1. Ran the Maven task "dokka:javadoc", which ended in a failure.
2. Re-ran the same task with -e switch for Maven (stack trace), and got the same error as referenced here: https://github.com/Kotlin/dokka/issues/347
3. Instead of trying the workaround suggested in the linked issue, I updated dokka to 0.9.18 and tried running dokka:javadoc again. This time around, it generated Javadoc for the individual classes, but failed to generate the index and layouts, likely because it ended with another exception:

java.lang.ClassCastException: org.jetbrains.dokka.javadoc.ClassDocumentationNodeAdapter cannot be cast to com.sun.javadoc.AnnotationTypeDoc at com.sun.tools.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:181) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:194) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:139) at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractDoclet.java:82) at com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:80) at org.jetbrains.dokka.javadoc.JavadocGenerator.buildPages(dokka-adapters.kt:16) at org.jetbrains.dokka.GeneratorKt.buildAll(Generator.kt:13) at org.jetbrains.dokka.GeneratorKt.buildAll(Generator.kt:23) at org.jetbrains.dokka.DokkaGenerator.generate(DokkaGenerator.kt:47) at org.jetbrains.dokka.maven.AbstractDokkaMojo.execute(DokkaMojo.kt:159) at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:134) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:207) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:153) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:145) at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:116) at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:80) at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build(SingleThreadedBuilder.java:51) at org.apache.maven.lifecycle.internal.LifecycleStarter.execute(LifecycleStarter.java:128) at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:307) at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:193) at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:106) at org.apache.maven.cli.MavenCli.execute(MavenCli.java:863) at org.apache.maven.cli.MavenCli.doMain(MavenCli.java:288) at org.apache.maven.cli.MavenCli.main(MavenCli.java:199) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:498) at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced(Launcher.java:289) at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:229) at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode(Launcher.java:415) at org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:356) at org.codehaus.classworlds.Launcher.main(Launcher.java:47)

1. Tried running dokka:dokka instead of dokka:javadoc. This generated all documentation correctly, but in simple HTML, rather than the Javadoc format.

Given that the Dokka version upgrade from 0.9.17 to 0.9.18 resulted in a partial success with the Javadoc format, I speculate that the Dokka contributors are still ironing out some issues with Javadoc generation.

Since Javalin's documentation is in Javadoc format, am I safe to assume you wish to keep it that way? If so, then getting dokka:javadoc to work would be the ideal solution.

I can try to submit the above exception to the Dokka issue tracker. I can also try to scan the Javalin code for instances of @Throws and replace them with @Throws(Throwable::class) as suggested on https://github.com/Kotlin/dokka/issues/347.

Please let me know if there's any particular way in which you'd like for me to proceed.

[nixxcode]

Okay, I think I have an answer for the Dokka exceptions. The issue appears to happen when Dokka attempts to document annotation classes in Kotlin.

Dokka team have already committed a fix that should be rolled out in 0.9.19.

https://github.com/Kotlin/dokka/issues/464

Might it be worth waiting for this fix, then trying to re-generate all the documentation via Dokka?

[ronMori]

came to similar conclusion as @nixxcode . Upgrade plugin version fixed javadoc gen issue.

two observations.

1. dokka:javadoc uneffect by plugin configuration. (same number of files/directories created)
2. missing index/overview/etc pages. how will these javadoc pages be integrated into static javadoc

[nixxcode]

@ronMori I am fairly certain the missing index/overview pages are a direct result of the exception I mentioned in my previous post under step 3.

I was able to tell Dokka to generate docs for only io.javalin.http and its sub-packages as a test, and this generated the index/overview pages successfully.

This is my Dokka config from pom.xml:

<plugin>
                <groupId>org.jetbrains.dokka</groupId>
                <artifactId>dokka-maven-plugin</artifactId>
                <version>0.9.18</version>
                <executions>
                    <execution>
                        <phase>pre-site</phase>
                        <goals>
                            <goal>dokka</goal>
                            <goal>javadoc</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <sourceDirectories>
                        <dir>src/main/java/io/javalin/http</dir>
                    </sourceDirectories>
                </configuration>
</plugin>

EDIT: Unsure why formatting is not being preserved. Is insert code no good for posting xml configs?

EDIT2: Wonderful, triple ticks fixed it. Thank you @tipsy

[tipsy]

Thanks @ronMori and @nixxcode for looking into this.

Since Javalin's documentation is in Javadoc format, am I safe to assume you wish to keep it that way? If so, then getting dokka:javadoc to work would be the ideal solution.
I can try to submit the above exception to the Dokka issue tracker. I can also try to scan the Javalin code for instances of @throws and replace them with @throws(Throwable::class) as suggested on Kotlin/dokka#347.
Please let me know if there's any particular way in which you'd like for me to proceed.

I don't have particularly strong opinions on this, but Javadoc is the "standard", so I think it makes sense to stick with that. Bumping and/or fixing the annotations is fine.

---

Unsure why formatting is not being preserved. Is insert code no good for posting xml configs?

Multiline code should be formatted with three ticks:

[nixxcode]

@tipsy I will try to upgrade to Dokka version 0.9.19 manually first, to see if the inclusion of https://github.com/Kotlin/dokka/issues/464 fixes the issue. If it does, we can simply wait until it's released on Maven and upgrade.

Will report back as soon as I've had a chance to try it.

[nixxcode]

Okay, I cloned the Dokka repo and applied the commit listed in https://github.com/Kotlin/dokka/issues/464

Success! All Javadoc for Javalin generated without error, and Kotlin files are all present and fully documented alongside Java.

This fix will be released as part of Dokka version 0.9.19. We can wait for its release, then update and re-generate all Javadoc via Dokka.

[tipsy]

Nice, thanks for looking into this!

[tipsy]

@nixxcode any update on this?

[nixxcode]

@tipsy Sadly not, Dokka hasn't been updated since I originally had a look at the issue.

To generate Javadoc for Kotlin files at present, you'd need to do a release running the development build of Dokka, which is not published on Maven.

Or you'd need to change your release process to include and sign pre-generated Javadoc. Both of these options add a lot of complexity.

[tipsy]

Thanks for the update, I'll be patient :)

[nixxcode]

Always happy to help out where I can!

[tipsy]

https://github.com/Kotlin/dokka/releases/tag/0.10.0

[tipsy]

I ran dokka:dokka and dokka:javaDoc locally, and everything seems to work fine!

[derekatgithub]

Still cannot find the class " io.javalin.http.Context" under version 3.7.0

Check the link
https://javadoc.io/doc/io.javalin/javalin/latest/index.html

[Zsuark]

This ticket should be re-opened. It has not been resolved.

There is still no javadoc for the Context class.

[tipsy]

Are you using the latest version?