Scala3doc: improve stdlib loading #10593
Conversation
A separate task is no longer necessary.
abgruszecki
changed the title
|
Alright, there's one problem with this PR: it now documents multiple projects together, and those projects actually use different docstring syntax. See : https://scala3doc.virtuslab.com/pr-improve-stdlib-loading/scala3/-scala%203/-a-p-i/scala/-predef.html?query=object%20Predef%20extends%20LowPriorityImplicits . |
|
We do get the new definitions documented, though: https://scala3doc.virtuslab.com/pr-improve-stdlib-loading/scala3/-scala%203/-a-p-i/scala/-predef/summon.html |
The best fix I can think of is to set default syntax to wiki and add |
| // NOTE we avoid documenting definitions in the magical stdLibPatches directory; | ||
| // the symbols there are "patched" through dark Dotty magic onto other stdlib | ||
| // definitions, so if we documented their origin, we'd get defs with duplicate DRIs | ||
| if !root.symbol.show.startsWith("scala.runtime.stdLibPatches") then |
There was a problem hiding this comment.
I think we should turn this into setting and do not hardcode in the logic itseld (I can see usage for excluding bits from documentation)
There was a problem hiding this comment.
Can we have a separate issue for that? I can already see a bunch of things that would need to be considered with such an option (should the option take a list of full package names? a list of FQN string prefixes?) and I'd rather discuss them separately.
| /** Extracts members while taking Dotty logic for patching the stdlib into account. */ | ||
| def extractPatchedMembers: Seq[Member] = { | ||
| val ownMembers = c.extractMembers | ||
| def extractPatchMembers(sym: Symbol) = { |
There was a problem hiding this comment.
Shouldn't that logic be placed into TASY? I mean people may wan to parse tasty from stdlib and they will be really supprised what they will get
There was a problem hiding this comment.
Tasty Reflect is already aware of how the compiler patches stdlib definitions. Our problem is that we rely on class bodies to document classes, and those aren't patched.
We can open a separate issue for patching class bodies as well.
|
I think we can use similat approach as for sourcelinks or we will use for extenrnal docs. So we can either pass a single value (as we do now) or pass pairs |
I agree, but the filePattern should probably reference the path to the Right now I'm looking into just defaulting to wiki syntax for stdlib docs. That may require the least changes to already-existing docstrings. |
|
Lets merge it for now and remove hardcoded bits in follow up PRs |
This PR fixes the issue that prevented us from loading stdlib together w/ other artifacts, and makes the doctool aware of stdlib patching going on in the compiler.