Please consider to support line-prefix /// as marker for ScalaDocs in similar fashion as Java supports /// from JDK 23 with JEP 467: Markdown Documentation Comments.
Such prefix has several advantages:
it has fixed width
formatting tools and IDEs could not reformat line-prefix differently
there are no “forbidden” sequences of text, like */
Example of almost valid and ugly ScalaDoc:
/** start of ScalaDoc
* 2nd line aligned to first `*` on first line
* other line reformatted to alight with second `*` of first line
also valid line
ScalaDoc breaking line contains `*/` sequence
*/ // zero, one, two or more spaces before `*` are valid, but width is inconsistent depending on used formatting tool
Intriguing. While I don’t think we have any need to follow Java’s lead, I do rather like this enhancement on its own merits, and I’d likely use it heavily.
Offhand, it doesn’t look likely to break much, although it’s possible that some projects use /// as a convention for their own reasons. (I often use a long line of /s as a visual separator in my code, so hopefully that wouldn’t break.)
Probably worth at least a pre-SIP, IMO, if someone is motivated to write it up.
Not to be a curmudgeon, but could such a feature be introduced first as a Warning,
with no change of behavior, and, in a next version, actually silently use the new behavior?
I know that I use variants of “///” all over the place, in a rather large code base.
Generally when commenting out a large block of existing “//” comments, or
scala-cli directives.
I’d be pretty unhappy if things changed/broke with a Scala upgrade, especially a minor one.
Yes, it would be in the Fine Release Notes, but would be easy to miss.
If I thought I was the only one, or even in a small minority of people who would be hosed
by this proposed change, I would focus on the task demanding my attention, but I
suspect this is the kind of change, if done in one step and without opt-in, makes more
people unhappy than happy.
