Javalin: Add documentation to public API

[ShikaSD]

Hi, have noticed, that the public API is lacking a bit of documentation. Could you point to most of the places considered "public API" or "extensible API", so I could help you with that?

[tipsy]

Do you mean Javadoc?

[ShikaSD]

@tipsy exactly

[tipsy]

I've been actively trying to avoid creating and maintaining Javadocs, I prefer just having the docs online. Could add links I suppose?

[ShikaSD]

Alright, though I am concerned about two cases:

• Maintaining offline support if one does not have the internet connection, e. g. in an aircraft or smth
• Giving some quick clues for the ones navigating through the library in IDE.

For those cases, the docs could be defined as the short clues where to go and how to use API, whereas most of the documentation with examples will be online. I suppose these additions could make the library friendlier to newcomers.

[tipsy]

@ShikaSD Both valid points. I find comments a little distracting, but I can always just fold them in IntelliJ. Please go ahead, I appreciate the effort.

[ijks]

I just found this issue because the current online docs say that PRs adding doc comments wil be rejected, but if it's not a problem, maybe that part should be updated?

I'd also like to add that doc comments are very useful for documenting an API in depth, and documenting what behavior a method or class should have. Examples can even be added if possible. Furthermore, it's easier to keep them in sync with code changes, since they're right next to the relevant code.

I am personally having trouble choosing what web library/framework to use for a Kotlin-only project, since not a lot of the available options (that are Kotlin-focused) have documentation that is thorough enough. Having both guide/reference level docs (which are very well done in this case :+1:) _and_ more in depth API docs would really give this framework an edge, for me.

[tipsy]

This is high priority now. All other PRs will be on hold until the Javadoc is done.

@ijks I've changed that section of the webpage now.

Status

| File | Status | Assignee |
| --- | --- | --- |
| Javalin.java | Almost done | @tipsy |
| ApiBuilder.java | Almost done | @tipsy |
| Context.kt | Almost done | @tipsy |
| WebSocketHandler.java | Almost done | @tipsy |
| WsSession | Done | @tipsy |
| Functional interfaces | Almost done | @ShikaSD |
| Dataclasses | Almost done | @ShikaSD |

[ShikaSD]

Do you think functional interfaces and dataclasses (which?) should be addressed?

[tipsy]

I think 3-5 lines for each explaining how they're used couldn't hurt

FunctionalInterfaces:

• Handler
• ExceptionHandler
• ErrorHandler
• AccessManager // probably more important than the others
• EventListener

Data classes:

• BasicAuthCredentials
• UploadedFile

[ShikaSD]

Can take those.

[tipsy]

@ijks @plombardi89 @gkopff could you have a quick look through of the current master and tell us what you think? Preferably by cloning the current master and clicking through the actual project, but if that's too much effort it would also be helpful if you would just look through the main classes:

• https://github.com/tipsy/javalin/blob/master/src/main/java/io/javalin/Javalin.java
• https://github.com/tipsy/javalin/blob/master/src/main/java/io/javalin/ApiBuilder.java
• https://github.com/tipsy/javalin/blob/master/src/main/java/io/javalin/Context.kt

[tipsy]

I'll just close this, as most of the public API has been documented. There's always room for improvement, but it shouldn't be a separate issue anymore.