Fixup Most Of The ScalaDoc Issues #4020
Conversation
This commit corrects _most_ of the Scaladoc issues.
The Scaladoc issues fell into one or more of the following categories.
* Reference was not fully qualified.
* For external links, and for _some_ internal links, Scaladoc wants a fully qualified symbol to link against, even if the given symbol is in scope.
* For example, `[[Kleisli]]` -> `[[cats.data.Kleisli]]`.
* Third party library is not exposing `apiURL` in the POM, or is doing so incorrectly.
* This prevents SBT from automatically configuring the URLs for linking into the third party Scaladoc.
* To solve this issue `ScaladocApiMapping` was added in `project/`. This contains manual code to construct the linking,
using `https://javadoc.io` if the project does not provide another more specific URL.
* Overloaded references
* These are warnings caused by a reference to an overloaded symbol.
* These were _not fixed as part of this commit_. I tried for quite some time, but I just couldn't get the disambiguation logic to work.
* The Scaladoc was just wrong.
* In this some cases the Scaladoc just didn't link to a real symbol, usually because of typos or change symbol names.
Prior to this commit there were 35 warnings issued for Scaladoc (you need to enable `link-warnings` to see this), now there are 5 and they are all related to overloaded symbols.
There was a problem hiding this comment.
Oh, very cool. I bet we could cherry-pick back most of this and keep the branches in better sync. I'm being a bit fanatical about pushing work to series/0.21, because right now it's merging to five(!) branches (dotty, main, cats-effect, and cats-effect-dotty to make sure the two big ports come together.
|
@rossabaker Yikes, that's a lot of branches to manage. Do you want me to open separate PRs cherry picking this to each of those or do you want to do that on your end? |
|
Oh gosh. I meant to open this against Is that what you were asking me to do? @rossabaker |
|
@rossabaker I'm curious on your thoughts about removing -no-link-warnings from the build. Warnings are currently configured to be fatal in that scope, and it might be nice to have good viability on when a Scaladoc link is bad, especially since Scaladoc's linking rules are so arcane. |
|
I'm used to cherry-picking commits back to series/0.21. Our default is main, so it can show all the recent activity, but but the vast majority of our PRs start on 0.21 right now. But thanks for resetting! I think we got so frustrated with the arcane rules we gave up and turned on that flag. But if we've got it cleaned up and can catch new ones, I'm in favor of turning it off and seeing how it goes. |
Fixup Most Of The ScalaDoc Issues
Fixup Most Of The ScalaDoc Issues
This commit corrects most of the Scaladoc issues.
The Scaladoc issues fell into one or more of the following categories.
[[Kleisli]]->[[cats.data.Kleisli]].apiURLin the POM, or is doing so incorrectly.ScaladocApiMappingwas added inproject/. This contains manual code to construct the linking,using
https://javadoc.ioif the project does not provide another more specific URL.Prior to this commit there were 35 warnings issued for Scaladoc (you need to enable
link-warningsto see this), now there are 5 and they are all related to overloaded symbols.