I'm really excited about the new Markdown support in Java 23's Javadoc! This update is based on Commonmark, which makes it way easier to format documentation. However, I'm left wondering if there are any plans to add support for math equations. I've noticed that Commonmark doesn't natively support math; it needs a plugin. In the past, I've struggled with writing out math in raw HTML, which can be quite messy to read. It would be amazing to have something like LaTeX syntax or a simpler format for inline math. For example, being able to write `$ x^2 = a*b $` instead of dealing with escaping HTML tags. I even tried adding this math code to a Javadoc file, but it didn't render as expected. Does anyone know if there are plans for this feature?
6 Answers
I just want a way to include mermaid diagrams in Javadoc as a related feature!
I checked JEP 467, and unfortunately, it doesn't mention any math support at all. It's possible that native LaTeX support is too niche for many developers, so you might be out of luck for now. But yeah, that would be incredibly useful!
You can create custom doclets to extend the standard Javadoc functionality. It might require more work, but it's an option to explore.
One workaround might be to create a script that adds MathJax into the compiled HTML. It won't help in IDEs, but at least it would render in browsers. You could also consider implementing a `@math` annotation to convert to MathML during HTML generation.
I hear you! It would be ideal to incorporate a Markdown plugin instead of these hacks. Back in the day, I found some Javadoc plugins that supported Markdown; it's doable but tricky.
If you're interested, I found this podcast episode discussing Javadoc updates. They mentioned that they're observing how developers use the new features but don't expect big changes anytime soon.
Thanks for the heads up! I’m always looking for info on these updates.
Why not give MathML a try? It's what Wikipedia uses for math formulas, particularly in Firefox. It's just standardized HTML for math, but you might need to test if you can use it in Javadoc comments.
True, but if there's enough interest, maybe it could be proposed as a feature request down the line.