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.
