News for hackers. Stuff that matters.
Re:On Markdown in Java documentation comments by seadan83 on Tuesday January 24, 2023 @10:19PM (#34513965)
For writing lists, this is going to be a real godsend! I'm really happy to hear this is being considered for first class support. It's hard to understate the value of making lists in documentation easier to both read & write

Second, adding XML snippets* into documentation is going to become far easier with markdown. It's common to want some documentation that says: "add this XML example to your config file: ...{xml}...". Generally at that point the HTML generation is completely thrown out of the window for the sake of the documentation being able to be usable with ready-to-go copy/paste examples. (Grant-it, I've yet to really work on any project that uses generated javadoc documentation. [Which just perhaps shows I have never contributed to any core java libraries or anything meant tob be consumed as a java library]. But for example, my advice to colleagues that I work with for documentation is to focus on audience and to take note that HTML-javadoc is never generated for the project they are working in. So don't optimize for a generator that is never run, optimize readability for the actual dev sitting between their keyboard and chair that is reading the javadoc)

* Yeah, CDATA could be employed, but who wants to do that?

Re:On Markdown in Java documentation comments by seadan83 on Wednesday January 25, 2023 @03:11AM (#34515710)
Reply/edit. I realize actually.. cdata might be only for XML. Being able to put raw XML examples without everything being escaped is really quite major.