Will Java's Markdown Javadoc Ever Support Math Equations?
Asked by
SunnySquirrel42
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?
Answers
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.
Reply to this answer
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.
Reply to this answer
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.
TechieTammy77: 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.
Reply to this answer
You can create custom doclets to extend the standard Javadoc functionality. It might require more work, but it's an option to explore.
Reply to this answer
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!
MathIdeas83: True, but if there's enough interest, maybe it could be proposed as a feature request down the line.
Reply to this answer
I just want a way to include mermaid diagrams in Javadoc as a related feature!
Reply to this answer
Add your answer
Answers are reviewed before publication.
BusyBee82: Thanks for the heads up! I’m always looking for info on these updates.