I 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).
No 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.
I'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 ...
Hard 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
You 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.
