# Javadoc and Markdown
**URL:** https://bnd.discourse.group/t/javadoc-and-markdown/401
**Category:** DEVELOPMENT
**Created:** [December 15, 2023, 9:15am UTC](https://bnd.discourse.group/t/javadoc-and-markdown/401 "2023-12-15T09:15:27Z")
**Posts on this page:** 7
**Page:** 1
### Author:  [@pkriens](https://bnd.discourse.group/u/pkriens)
#### Post date: [December 15, 2023, 9:15am UTC](https://bnd.discourse.group/t/javadoc-and-markdown/401/1 "2023-12-15T09:15:27Z")
The predecessor to bnd got started in 1999 and Bndtools in 2005 I think. A major regret for bnd is that I did not separate API and implementation. When I started the idea was that the API were the properties, not the code. 25 years later this was proven wrong. The library is used in hundreds of places and we have to live with its flaws.
Our javadoc for public API is not very useful nor well maintained. In the last few years I am trying to do better. However, javadoc sucks majorly. In 1996 when Java escaped the lab, the idea of formatting with HTML seemed a good idea, like checked exception. 30 years later not so much.
The consequence of HTML formatting is almost impossible to read in the source code, the tags get in the way. Like XML, reading HTML is torture for me. These \*ML’s were not designed for human consumption. If our Javadoc was widely read, there might be some value in this. However, I am quite confident that 99,9% of the time people are staring at the HTML diarrhea in the source code to understand an API.
Markdown is a lightweight markup language with plain-text formatting syntax, created by John Gruber and Aaron Swartz in 2004. Its design goal was simplicity and readability, making it easy for text to be converted to HTML and other formats. Markdown was born out of a desire to write content for the web more easily without the cumbersome tags and formatting that HTML requires. The language gained popularity due to its user-friendliness. Github would be a different experience without it.
The combination of Javadoc and markdown seems to be made in heaven? The source code remains readable and the output can still be, with the proper Javadoclet, be made to leak really good. There are details, the formatting in the IDE has to be disabled and quick fixes likely do not work.
This seems such an obvious idea that I am curious why it is not widely adapted?
Still, if I can convince the bnd team members, I’d like to pursue this direction.
---
### Author:  [@chrisrueger](https://bnd.discourse.group/u/chrisrueger)
#### Post date: [December 15, 2023, 10:39am UTC](https://bnd.discourse.group/t/javadoc-and-markdown/401/2 "2023-12-15T10:39:17Z")
> [@pkriens](#):
>
> Still, if I can convince the bnd team members, I’d like to pursue this direction.
Markdown would be great.
Seems there is also a recent [JEP Draft](https://openjdk.org/jeps/8316039)
---
### Author:  [@mnlipp](https://bnd.discourse.group/u/mnlipp)
#### Post date: [December 15, 2023, 5:22pm UTC](https://bnd.discourse.group/t/javadoc-and-markdown/401/3 "2023-12-15T17:22:28Z")
Been using this for years… ([GitHub - mnlipp/jdrupes-mdoclet: A javadoc doclet that handles Markdown comments](https://github.com/mnlipp/jdrupes-mdoclet)). Together with [PlantUML](https://github.com/mnlipp/jdrupes-taglets) nothing can beat this for documentation ([non-trivial example](https://mnlipp.github.io/jgrapes/javadoc-webconsole/org/jgrapes/webconsole/base/package-summary.html)).
---
### Author:  [@pkriens](https://bnd.discourse.group/u/pkriens)
#### Post date: [December 18, 2023, 7:49am UTC](https://bnd.discourse.group/t/javadoc-and-markdown/401/4 "2023-12-18T07:49:05Z")
Nice work!
I like PlantUML and used in several other places, it would not be a primary concern. My main problem is that maybe 0,1% of the code is read via Javadoc. I think we should therefore optimize reading the code.
In the case of the OSGi spec I’d say PlantUML would be great because the API is mostly read through the Javadoc but for bnd I think it suffices to make the code markdown.
Would be nice if we could convert the little HTML we have to markdown automatically.
---
### Author:  [@mnlipp](https://bnd.discourse.group/u/mnlipp)
#### Post date: [December 18, 2023, 8:55am UTC](https://bnd.discourse.group/t/javadoc-and-markdown/401/5 "2023-12-18T08:55:31Z")
> Would be nice if we could convert the little HTML we have to markdown automatically.
I wouldn’t spend time on that. As markdown can contain HTML, existing comments should simply work even when processed with a markdown doclet. I’d start writing new comments with markdown and convert existing ones manually when they need an update.
---
### Author:  [@chrisrueger](https://bnd.discourse.group/u/chrisrueger)
#### Post date: [February 29, 2024, 4:42am UTC](https://bnd.discourse.group/t/javadoc-and-markdown/401/6 "2024-02-29T04:42:20Z")
> [@chrisrueger](#):
>
> Seems there is also a recent [JEP Draft](https://openjdk.org/jeps/8316039)
Seems to be a candidate since 2 days ago 😃
---
### Author:  [@pkriens](https://bnd.discourse.group/u/pkriens)
#### Post date: [March 1, 2024, 11:00am UTC](https://bnd.discourse.group/t/javadoc-and-markdown/401/7 "2024-03-01T11:00:20Z")
Sounds great!
Just got the Java Newsletter. Its interesting that data oriented programming is going full steam. I love the records and I am seriously thinking enabling Java 17 preview to get the pattern matching features.
I am old OO guy but I’ve realized since forever that when your data is standardized in the outside world, don’t put an abstraction around it. Crazy about DTOs and records are the perfect DTOs.