Scaladoc: realign -doc-source-url behavior with 2.12

[lrytz]

Summary

• In the common case, build tools pass absolute paths to the compiler for source files to compile
• -sourcepath is used to relativize them
• In 2.12.11, the relativized path starts with a /, so base€{FILE_PATH_EXT} becomes base/src/...
• #10502 changed relativization to use srcpathUri.relativize(fileUri), which doesn't have a leading /
• Fix: for a relative path, foo/€{FILE_PATH} and foo€{FILE_PATH} both emit foo/relative/path/File (insert / if a word character precedes €{FILE_PATH}). No such magic for absolute paths (if -sourcepath is not specified or is not a prefix of the file).

What happens without -sourcepath:

• 2.13.11 used the path that the compiler got on the command line. So scaladoc a/B.scala would insert a relative path.
• 2.13.12 relativizes source paths to the current directory because Paths.get("").toUri is the current directory
• I changed it to use an absolute path. As build tools pass absolute paths to the compiler, the behavior is the same as in 2.13.11 in the common case.

Fixes scala/bug#12867

[som-snytt]

I have a couple of branches. I'll comment if either contains a break-through.

  issue/12867-doc-url
  issue/12867-scaladoc-source-link

One was from Sept 13, the longer one from Sept 20, when apparently it occurred to me to fix Scaladoc tickets?

commit d25e06dc81cd60d0efb9ffaf9239b65f341dd2cb (HEAD -> issue/12867-scaladoc-source-link)
Author: Som Snytt <som.snytt@gmail.com>
Date:   Thu Sep 21 17:40:22 2023 -0700

    more

commit 714275ffd3ac81506dd5e15081107b1c9b38038e
Author: Som Snytt <som.snytt@gmail.com>
Date:   Wed Sep 20 20:48:09 2023 -0700

    Minor refactor for reading

commit 6b994a4f30ee0cb78a5f2a28b0c6279467c890f6
Author: Som Snytt <som.snytt@gmail.com>
Date:   Wed Sep 20 19:10:03 2023 -0700

    No inheritdoc on Iterator.sameElements

commit 51885feabfae5030b6c473db1bf463418b81d2d2
Author: Som Snytt <som.snytt@gmail.com>
Date:   Wed Sep 20 18:36:49 2023 -0700

    Library leverages canonical url

commit 2df1a5fff4b745102203e1d68c6e62c6552fd3f9
Author: Som Snytt <som.snytt@gmail.com>
Date:   Wed Sep 20 17:28:36 2023 -0700

    Clean up doclet newinstance, avoid null currentRun

[lrytz]

@SethTisue could you review this? I summarized everything in the description.

[SethTisue]

I've looked through this and I can't think of a flaw or fresh angle, so I'll hit "Approve", but @som-snytt, you analyzed the situation pretty thoroughly at scala/bug#12867 (comment) ; would be good to have your signoff before merge, if you can spare the time

also perhaps @armanbilge would like to have a look?

[som-snytt]

my test dirs from that day...

...    4096 Sep 20 13:38  t12876
...    4096 Sep 20 14:37  t12867

[som-snytt]

I happen to be tired and lacking focus at the moment, so reading even this much regex is like, I'm not going to read any more regex until after New Year's.

[som-snytt]

NBD I tried the crusty way. https://github.com/scala/scala/compare/2.13.x...som-snytt:scala:test/t12867?expand=1

[lrytz]

I'm all for a simpler regex, thanks a lot for your cleanup.