5 ms·
JEP 467: Markdown Documentation Comments
- jonasenordin 3y agoI use a very low-tech solution: I stick a <pre> tag at the start of javadoc comments, and make liberal use of empty lines for spacing. So I don't use any advanced html tags and stuff. Of course I use @link, which is the most useful feature of javadoc. BTW, maybe the 'meaning' of <style> tags should be clarified for ambitious documenters... It seems they only affect the one javadoc they are inside of, which is pretty useless.
- MrBuddyCasino 3y agoWho else prefers AsciiDoc syntax?
- splittingTimes 3y agoHere. Did manage to make it work with AsciiDoclet?
- lenkite 3y agoSame here. So pissed that Markdown won the "docs battle". Tables and higher-level semantics in Markdown are a nightmare compared to Asciidoc.
- troupo 3y agoFor markdown comments though AsciiDoc tables are horrible
- java-man 3y agoHow different is the javadoc markdown dialect from that of github?
- wpollock 3y agoGithub Flavored Markdown (GFM) is a superset of commonmark. The differences are indicated in the GFM spec at https://github.github.com/gfm/ https://github.github.com/gfm/.
- masklinn 3y agoExtensions aside the major difference is the handling of line breaks: in markdown they get discarded, you need two to separate paragraphs. In GFM, individual line break are translated to line breaks in the output.
- infogulch 3y ago> Markdown documentation comments are written in the CommonMark variant of Markdown. There are enhancements to links, to allow convenient linking to other program elements. Simple GFM pipe tables are supported, as are all JavaDoc tags. https://openjdk.org/jeps/467#Syntax https://openjdk.org/jeps/467#Syntax
- ecshafer 3y agoI don't see the need for this. Java having a Mardown parser within its compiler just seems wildly out of scope for not a lot of benefit. This seems like the use case of an IDE extension, or a website that host code, not the compiler itself.
- anatnom 3y agoThe javadoc tool is useful for creating simple HTML documentation directly from the source code. But you end up choosing between making the documentation comments legible as source code or legible as HTML. If HTML javadoc is important to a project, this often means that HTML-in-java-comments will prevail, which in turn means that the developer experience of working on and maintaining those docs is poor. Eclipse and IntelliJ both do good HTML rendering of these comments in mouseover/etc displays, but it is quite annoying to open a file and then need to hover the mouse over the main type just to make the documentation legible.
- deleted 3y ago[deleted]
- tpmoney 3y agoI'd argue the fact that Java included an html parser to parse and generate JavaDoc as part of the core langue has made it still one of the best languages for finding and reading documentation. Yes, many smaller packages and libraries are just blank auto-generated docs that tell you nothing, but the packages with a well written set of javadocs are wonderful to work with. And a standard with a built in parser means once you know how to read it one place, you know how to read it anywhere. And your IDE will always know how to parse it. Rust likewise has a standard and parser built in (markdown in this case) and even took it a step further and allowed your example doc code to be runnable and testable. Personally I've long wanted to see JavaDoc allow markdown. As the JEP examples show, trying to make any javadoc comments that format nicely for the javadoc parsers means making documentation that's hard to read when you're in the code itself. Even the most basic of markdown parsing covers probably 90% of what you'd put in javadoc, and would make reading (and writing) good JavaDoc that much better.
- kelnos 3y ago
- marknote 3y agoNice, markdown can help to make java comment easier.
- Georgelemental 3y agoRust has this, it's a great QOL feature, glad to see it spread widely
- bodeadly 3y agoI would argue that API doc text should not be inlined with code at all. It's just noise. It should be in a separate XML file with a minimal schema. Then building the javadoc is just running xsltproc with a javadoc.xslt. Then you also have the option to use your own xslt file to generate pages that integrate with your com / org site (like learn.microsoft.com).
- rockwotj 3y agoHard disagree. I often read header files directly for documentation and think it’s pretty great. Makes it easy to delve into the source if needed and I dont have to leave my terminal/nvim
- riwsky 3y agoYou would be wrong. The closer documentation is to the code, the more likely it is to be seen, and to be updated. Reading and writing the docs are more common operations than “writing a new doc transformation tool” by at least 4 or 5 orders of magnitude; the ease of writing new doc transformation tools should not be the determining factor in a design.
- kelnos 3y agoNo thank you. As someone who has to read code in addition to writing it, it's great to have the doc comments right there, so I don't have to open and search through another document. There's also the issue of keeping things up to date: it's much more likely that a programmer is going to keep docs up to date if the doc is right there along with the code than if it's in a separate file. Not to mention... XML... ugh, no, let's not.
- bodeadly 3y agoI'm not a fan of XML either with the exception of one purpose which is document processing using XSLT. XSLT is THE correct way to generate documents. Markdown is extremely limited by comparison. And I'm not suggesting that there would be no documentation in the code. Javadoc is written for consumers of the code being document. That is incorrect. The comments should be optimized for the developers of the code itself. And it should not explain what the code does if you can just read the code itself. So again, IMO, javadoc is a mistake. It mixes up two largely different things. Also, when you downvote someone, it's not supposed to be because you don't agree with their view. You downvote someone when they say something that does not contribute to the discussion. But do what you will ...
- MBCook 3y agoI can’t wait. As someone spending much of their time in Java I much prefer the idea of markdown to HTML for writing Javadoc. HTML may produce nice output when everything is processed, but inline it’s ugly and distracting. This is exactly the problem Gruber designed markdown to fix. Personally I’m not big on /// as it’s pretty visually heavy. I understand their reasoning for not allowing it in /** */ blocks. I’d be happy with maybe //** */ or /*** */, but I’m just bike-shedding. Its a great QOL feature idea and I’ll be happy when I can start using it.
- runarberg 3y agoWasn’t there a whole discussion like 5 years ago about deprecating multi-line doc comments (/** */ and /*! */) in Rust, in favor of using /// and //! exclusively, but a blind developer raised a pretty important accessibility issue with that, because their screen reader would always interject “slash slash slash” in the middle of a sentence when they were reading the docs. I was trying to find the issue in a web search, but failed. If I remember correctly it was important to keep multi-line doc comments in the language even if they are seldomly used, because it allows developers using assistive technology the possibility to read doc comments uninterrupted.
- Atotalnoob 3y agoWhile accessibility is important, /// is used in the .net world, perhaps the screenreader should handle that scenario?
- runarberg 3y agoI remember the issue being quite a bit ago, so perhaps the tooling has improved in the meantime (I only use screen readers for testing, not developing, so I wouldn’t know). If not, perhaps Java doing this will be the catalist. I imagine that it isn’t hard for developers with screen readers to have an editor macro turn /// comments into /** and back in the rust world. But if /// were the only option then there is no such workaround for developers and their only options are to endure or request the improvements (or send a PR if using open source tools).
- lincpa 3y ago[dead]
- jonhohle 3y agoI used pegdown-doclet for this for a long time. It made documentation in code as easy to read as the generated docs. I don’t think most developers knew that JavaDoc was HTML to begin with (or evernlooked at the rendered docs).
- brabel 3y agoJavadocs are not HTML, it's just a small subset of HTML that's actually supported.
- layer8 3y agoYou can put arbitrary HTML body content in javadoc. There is no specification that limits it, and the standard doclet just passes it through as-is. This is similar to HTML in Markdown, incidentally.
- jonhohle 3y agoFrom the JavaDoc docs[0] under the heading “Write comments in HTML”: > The text must be written in HTML with HTML entities and HTML tags. You can use whichever version of HTML your browser supports. 0 - https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html https://docs.oracle.com/javase/8/docs/technotes/tools/window...
- brabel 3y agoOk, I admit I probably read this a long time ago and didn't bother to ever check as I never see anything very advanced in HTML used in Javadocs... But if you're going to link to the docs, at least link to the modern Java Documentation, not some ancient Java 8 version of the javadoc tool: https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html https://www.oracle.com/technical-resources/articles/java/jav...
- jonhohle 3y agoThat was the first Oracle link that appeared in search results for me. I think it’s probably more relevant to go backwards however. Javadoc 1.2, for example, has the same quote I originally included - https://web.archive.org/web/20010129031800/http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/javadoc.html#examples https://web.archive.org/web/20010129031800/http://java.sun.c...
- gudzpoz 3y agoAlthough it is not mentioned in the JEP, I wonder if we can use fenced code blocks as @snippet tags [1]. Of course one can still use {@snippet}, but fenced code blocks seem to me to be the go-to for code quoting in Markdown. ```java id=example class HelloWorld { public static void main(String... args) { System.out.println("Hello World!"); // @link substring="System.out" target="System#out" } } ``` (However, some JS highlighting libraries will strip pre-existing HTML in the code (e.g. PRISM.js [2], as is mentioned in the JEP), negating the @link tag above. Highlight.js [3] seems fine though.) [1] https://openjdk.org/jeps/413 https://openjdk.org/jeps/413 [2] https://prismjs.com/faq.html#if-pre-existing-html-is-stripped-off-how-can-i-highlight https://prismjs.com/faq.html#if-pre-existing-html-is-strippe... [3] https://jsfiddle.net/LFJKR/ https://jsfiddle.net/LFJKR/
- pron 3y agoNot yet, but we'd like to have that.
- oaiey 3y agoAre Javadocs still a thing? When I was young and coded Java the last time that was all fancy and normal to do. But today? Also wish C# would switch to Markdown comments instead of this XML nonsense. This JEP looks so clean.
- creatonez 3y ago> Are Javadocs still a thing? When I was young and coded Java the last time that was all fancy and normal to do. But today? Automated API documentation based on code comments never really died, but the popularity of dynamically typed programming languages had a lot of devs writing API docs separately by hand for a while. Even though some dynamically typed languages had tools for it, they were ignored because nobody had reliable IDE integrations for Javascript/Python, and maybe (?) because of a sentiment that it is a weird enterprise thing to do. Many open source projects adopted casually-written documentation more focused on usage examples, skipping out on detailed documentation of procedures that are deemed too obvious to need docs. But nowadays we are in a golden age of doc generator tools across various languages.
- adrianmsmith 3y agoWhat would you use instead of Javadoc if you didn't use Javadoc?
- usrusr 3y agoIt absolutely is. Perhaps not so much as in carefully thought out to become the only usage instruction ever needed and manually uploaded to the intranet for your tiny in-house lib, but as in all java tooling knows javadoc, expects its existence and presents it at every opportunity. It's the way to attach some description to a method and doing it any other way is considered wrong. Build plugins (or is it default by now?) pick it up for packaging and distribution through the maven repository hierarchy and when a library ends up in your dependency tree without a javadoc jar you suddenly remember that this is actually possible. What's dead in many environments is going fancy with the HTML. I think most codebases have nothing or very little in terms of formatting outside the @something keywords. Then the only trace of html is the pain of typing < instead of <. For things like emphasis, chances are people already write it in markdown snytax instead of html even assuming that the markdown will never be read in a formatted way.
- troupo 3y agoGive it to Java to look at nearly every other language and come up with a strictly worse implementation of a useful feature.
- cowsandmilk 3y agoWhat’s worse?
- troupo 3y agoThe requirement to have every line marked as essentially a single line comment, adding a lot of visual noise and basically requiring tool support to automate this tedious work.
- tpmoney 3y agoRust (and per another commenter, c#) both use the same styling. From having done rust development, you get used to it pretty quickly and it becomes no noisier than the repeated stars in the block comments. I’d prefer just having the comment block start with `/*#` personally since Java already standardized on block style comments but this is hardly “strictly worse [than all other languages]”
- layer8 3y agoRather than visual noise, it makes comments sections immediately recoognizable as such. Think of page-long comments containing code samples. The tool support is trivial, and you can always run a simple regex to fix it up. Line comments in general have the advantage that they can be trivially nested, and the nesting be immediately recognizable as such. For any new programming language, I would only support line comments, for that reason.
- troupo 3y ago> Rather than visual noise, it makes comments sections immediately recoognizable as such. As if they weren't recognizable as such before > The tool support is trivial, and you can always run a simple regex to fix it up. Why all this when you could avoid it from the start? > Line comments in general have the advantage that they can be trivially nested, and the nesting be immediately recognizable as such. Has nothing to do with and is not applicable to comments written in Markdown
- avgcorrection 3y agoThe worst thing about HTML as docs is that you have to encode your code. You should just be able to write the code for the programming language you are using directly in the docs. Anything else is just nuts.
- pron 3y agoWell, you do need things like emphasis, lists, headings etc., which aren't typically part of a programming language.
- avgcorrection 3y agoWhat do you mean? I’m talking about Java code inside javadoc, like code example docs.[1] That’s straightforward if the doc markup is MarkDown with code fences. The MarkDown code character backtick is especially great for Java since it’s not a metacharacter in the Java syntax. [1] I didn’t mean writing docs in Java itself, whatever that would look like.
- pron 3y agoOh, ok. Yeah, that's supported, but it's also supported today without HTML with the snippet tag (and @code tag).
- avgcorrection 3y agoOkay great. Thanks Ron :)
- euroderf 3y agoGolang tried the same thing. The result seems half-hearted but it does work and it's close to "normal" Markdown.
- bartekpacia 3y agoThat’s how comments also work in the Dart language and I really like it. Happy to see this change.
- difosfor 3y agoI wish TSDoc would also support this, not to mention get a little love and attention in general. The spec for code linking has never been finished and the tooling like typedoc is limited and cumbersome, not to mention inconsistent with how other tools like VS Code parse and show it.