Scaladoc: type rendering fixes and improvements

[Florian3k]

This PR introduces multiple fixes and improvements to type rendering in Scaladoc

• Fixed rendering of TypeRefs (A#B) and TermRefs (a.b.type)
• Fixed rendering of Tuple1[T] (previously (T))
• Fixed rendering of this.type (except for type bounds, see below)
• Types with @showAsInfix are rendered infix
• Correct parenthesizing around infix types, & types, | types and function types
• Type parameters of superclasses in inherited methods are substituted with actual types from inheriting class/trait (see scaladoc-testcases/src/tests/supertypeParamsSubstitution.scala)
  https://github.com/lampepfl/dotty/pull/17213/files#diff-93a78912075a9fdb34fefa437d191be59888cb723ccb244374e77033d9eca779R12-R20
• this and type are highlighted as keywords

fixes #16024
fixes #16143
fixed #16057
fixes #16084 (partially) - fixed rendering of Int instead of n.type and (This, n.type) instead of Split[This, n.type]. this.type in type bounds remains unfixed. I created separate issue for that #17226

Documentation with those changes has been deployed to https://scala3doc.virtuslab.com/pr-types-rendering-fixes/scala3/api/index.html

[Sporarum]

Looks amazing, great job !

I think we should keep/add parens anytime it's ambiguous however, see the proposed changes for more details

[Sporarum]

Thank you for addressing my comments

I found some other things, feel free to address them as well if you want to ^^
(I consider them non-blocking)

[Sporarum]

More nitpicking:
Would it be possible to only print the identifier (x$1) if it is required ?

Ex: [t] => (x: t) => t

I see two ways of doing so:

1. Look at whether the name is synthetic/mangled: ex prints as [t] => (x: t) => t
2. Look at whether the name is used on the rhs: ex prints as [t] => t => t

[Florian3k]

I'll look into that.

[Florian3k]

Let's leave that for future improvements.

[Sporarum]

Could you open an issue for it ?

[Florian3k]

Done: #17756

[Sporarum]

I'm not sure I understand why we need the a/A in theses, could you explain ?

[Florian3k]

This file is part of test consisting of 2 files: exports1.scala and exports2.scala

The test:
https://github.com/lampepfl/dotty/blob/ef974367932cb148bda152ed056183f319a9a2fc/scaladoc/test/dotty/tools/scaladoc/signatures/TranslatableSignaturesTestCases.scala#L96

exports2.scala for reference:
https://github.com/lampepfl/dotty/blob/ef974367932cb148bda152ed056183f319a9a2fc/scaladoc-testcases/src/tests/exports2.scala#L1-L12

So it's testing for exported member signatures in class B.

Signatures are rendered based on TypeRepr from Tasty.
For example TypeRepr for val x: HKT[List, Int] rendered in class B looks like this (not valid scala, this is slightly formatted output from println):

AppliedType(
  TypeRef(
    ThisType(TypeRef(TermRef(ThisType(TypeRef(NoPrefix,module class tests)),object exports1),class A)), // TypeRepr for class A
    type HKT
  ),
  List(
    TypeRef(TermRef(TermRef(ThisType(TypeRef(NoPrefix,module class <root>)),object scala),package),List), // TypeRepr for List
    TypeRef(TermRef(ThisType(TypeRef(NoPrefix,module class <root>)),object scala),Int) // TypeRepr for Int
  )
)

Based solely on this representation, signature that should be rendered is A#HKT[List, Int]

To be honest, I'm not entirely sure whether this is correct way to render signatures of exported members.
If this is not correct, we may want to add some additional logic for checking if current signature is of an exported member and render it in a different way, but I'm probably gonna need some help with that.

[Sporarum]

@sjrd or @bishabosha, you are very familiar with tasty, what do you think ?

[sjrd]

a.HKT[T, X] seems absolutely correct to me. Otherwise you would be defining B.HKT in terms of itself.

The A#HKT[List, Int] seem a bit suspicious to me. this prefix substitution (the so-called asSeenFrom operation) should be replacing this.HKT[List, Int] from A by a.HKT[List, Int] when created by an export a._.

In fact, the TypeRef seems even more suspicious. As is, it means A.this.HKT, not really A#HKT. But that's quite bad if that's the type given to a member of B, since such a type is only valid when you're inside A. It seems the compiler is doing something wrong here.

From the point of view of Scaladoc, I think it should display A.this.HKT for the TypeRef(ThisType(A), type HKT).

[Florian3k]

@Sporarum I fixed rendering of ThisType and removed parens around occurrences of the same operator

[Sporarum]

Perfect, then from my point of view, this is good to merge !