3 ms·

I 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

by MBCook 3y ago

I 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 ago
Wasn’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 ago
  While accessibility is important, /// is used in the .net world, perhaps the screenreader should handle that scenario?
  - runarberg 3y ago
    I 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).
tczMUFlmoNk 3y ago
One little syntactic serendipity of /// is that, together with the following space, the prefix is four characters wide rather than three in /** */ with the [Space][Star][Space] line prefix, which has some minor benefits in terms of consistent indentation. (In fact, this is true whether you use tabs or spaces!)
frant-hartm 3y ago
Same here. I am so used to /** * */ that I find this visually off-putting. Almost as much the string interpolation in string templates. /*** would be much better. Also /// will be read as a comment with a line starting with a slash until the tooling is updated.
- kaba0 3y ago
  Just for note, C# also does 3 slashes, so there is prior art.
  - MBCook 3y ago
    Ah perhaps that’s where it came from. I’ve never done C# so I didn’t know that. Thanks.
  - brabel 3y ago
    Interesting, Dart and D also support that syntax.
usrusr 3y ago
Same. My vote would certainly go to /*** */, and dropping the leading * on the intermediate lines while you're at it. Or go with an alternative like /*# and # on intermediate lines, because the demand for whitespace clarity is certainly bigger in markdown. I'm very used to consider line and block comments semantically different. To my mind block is javadoc (or for text addressed at the reader that is not meant for tools, in short for prose) whereas // is for killing source lines (and for killing block comments for tools). With the corollary that // would be absent from perfectly clean code, that removal of // is never wrong. In my own projects, I even add an exception mechanism for // that should be kept, they can be marked with ///*why*/, and why should better be good. "why" can be a key further explained in a regular block comment, the idea is that those lines can be cleanly enabled/disabled/removed with regex. On a very abstract level, I could describe my position as "languages should have multiple forms of comments that have clearly defined semantic differences". I consider this a paradigm change similar to how modern languages have started to declare one style guide the blessed one, even if technically whitespace is just as insignificant as in the old days of "do what you think is best". What I do miss, from the old doxygen days, is support for trailing comments for when you want to add a few short words to a field without begging for attention too much. Something like int count = 0; /** quuxes encountered */ And for inline javadoc in multiline argument lists, which I believe to become ever more common in the postOOP age. These could be implicit @param in the slurp javadoc, just like the markdown lists in the future work part of the JEP (where I to see a real benefit of magic headline/list pairs over repeated @param or @throws): void slurp( /** quuxes ready to be slurped */ int todo, /** quuxes slurped before */ int done ) { (Of course I'm mostly looking at KDoc here, where they already have markdown but where multiline parameter lists are even more common than in current/future java)

by MBCook 3y ago

runarberg 3y ago

Wasn’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 ago
While accessibility is important, /// is used in the .net world, perhaps the screenreader should handle that scenario?
- runarberg 3y ago
  I 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).

tczMUFlmoNk 3y ago

One little syntactic serendipity of /// is that, together with the following space, the prefix is four characters wide rather than three in /** */ with the [Space][Star][Space] line prefix, which has some minor benefits in terms of consistent indentation. (In fact, this is true whether you use tabs or spaces!)

frant-hartm 3y ago

Same here. I am so used to /** * */ that I find this visually off-putting. Almost as much the string interpolation in string templates. /*** would be much better. Also /// will be read as a comment with a line starting with a slash until the tooling is updated.

kaba0 3y ago
Just for note, C# also does 3 slashes, so there is prior art.
- MBCook 3y ago
  Ah perhaps that’s where it came from. I’ve never done C# so I didn’t know that. Thanks.
- brabel 3y ago
  Interesting, Dart and D also support that syntax.

usrusr 3y ago

Same. My vote would certainly go to /*** */, and dropping the leading * on the intermediate lines while you're at it. Or go with an alternative like /*# and # on intermediate lines, because the demand for whitespace clarity is certainly bigger in markdown. I'm very used to consider line and block comments semantically different. To my mind block is javadoc (or for text addressed at the reader that is not meant for tools, in short for prose) whereas // is for killing source lines (and for killing block comments for tools). With the corollary that // would be absent from perfectly clean code, that removal of // is never wrong. In my own projects, I even add an exception mechanism for // that should be kept, they can be marked with ///*why*/, and why should better be good. "why" can be a key further explained in a regular block comment, the idea is that those lines can be cleanly enabled/disabled/removed with regex. On a very abstract level, I could describe my position as "languages should have multiple forms of comments that have clearly defined semantic differences". I consider this a paradigm change similar to how modern languages have started to declare one style guide the blessed one, even if technically whitespace is just as insignificant as in the old days of "do what you think is best". What I do miss, from the old doxygen days, is support for trailing comments for when you want to add a few short words to a field without begging for attention too much. Something like int count = 0; /** quuxes encountered */ And for inline javadoc in multiline argument lists, which I believe to become ever more common in the postOOP age. These could be implicit @param in the slurp javadoc, just like the markdown lists in the future work part of the JEP (where I to see a real benefit of magic headline/list pairs over repeated @param or @throws): void slurp( /** quuxes ready to be slurped */ int todo, /** quuxes slurped before */ int done ) { (Of course I'm mostly looking at KDoc here, where they already have markdown but where multiline parameter lists are even more common than in current/future java)