3 ms·

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? Also wish C# would switch to Markdown

by oaiey 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? 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 ago
What would you use instead of Javadoc if you didn't use Javadoc?
usrusr 3y ago
It 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.

by oaiey 3y ago

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 ago

What would you use instead of Javadoc if you didn't use Javadoc?

usrusr 3y ago

It 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.