Scala3doc UI and UX improvements

[Katrix]

Seeing as most of the things in the old issue were dealt with and the issue closed, I thought I'd go check out the state scala3doc and see what lesser things that could probably be fixed next. Hope you don't mind.

Type members:

• Very low contrast on the extends part
• When clicking on a type member, the box the member is inside briefly expands before navigating off the page

Value members:

• Types have very low contrast
• Scaladoc groups value members into a few groups. The ones I found just looking around are: Constructors, abstract value members, concrete value members, deprecated value members. There are probably more. Scala3doc does some grouping, but would love some more here.
• Sort value members
• Filtering the value members is kind of limited currently, as it also looks at the documentation for the method. Scaladoc also does this, but I'd love if just like the global search, if you searched for def map for examplke, it would only show methods named map.

Misc:

• Scala3doc is adding unneeded and confusing type lambdas to type signatures
• The first paragraph of the scaladoc of a class is smaller than the rest.
• Some ": " values at the top of classes feels kind of unnatural at the moment. "Source: (source)" doesn't tell me that much. Scaladoc adds the name of the source where the class came from here. Companion object link also feels out of place here. It's not just metadata which is what I normally think of that section as, but an integral part of consuming the API of that class. I'd prefer to have it closer to the header, like scaladoc does.
• The list in the docs of Option seems to be ill formatted.
• Don't show annotations in the signature for class pages. They're already shown in the metadata section, and in many cases contain info that I don't care too much about like SerialVersionUID
• Port over the class, trait and object icons from Scaladoc. They really help to tell me what I'm looking at with a quick glance
• I'd love some larger margins and more padding around the place. Paragraphs, member blocks and more. Just in general a tiny bit larger margins and more padding.
• Narrower pages. Scala3doc currently uses the full width of the screen. On wider screens that can become pretty tiresome to read. Scaladoc sets a limit of 1140px. I don't know if that's a good limit (I'd say so, although maybe something that reacts to screen size a bit more?) but I think some limit should be added.

Also, is there a live link to an instance of the scala3doc that shows off some stuff? The main one for Dotty doesn't expand packages, and the old ones from before this got merged in here are dead.

[pikinier20]

Replying to some points of your feedback:

1. Scala3doc adds confusing type lambdas to type signatures and we are aware of that, but it's a problem related to TASTY - it generates the same type tree for type lambda and e.g. [_ :> T] construction and it's hard to disambiguate it.
2. It's a good idea to add source name instead of (source) text.
3. Companion object links as well as icons from Scaladoc are planned to be ported, there's already task for that which tbh should be transfered to this repo
4. I think we should filter some annotations like mentioned SerialVersionUID
5. There's live link to scala3doc there and there you can see some instances of community lib docs.

[Katrix]

Thanks for the links to updated instances. I've noticed that packages can't be expanded anymore. Is that a deliberate design decision?

Also some more notes on the sidebar that I just found. First off, you can scroll it horizontally.

Also, if you expand something so that the sidebar goes from not being scrollable, to being scrollable, then the arrows move. Would be best if they didn't. If it's hard to make them not move, then maybe just show the scroll bar at all times?

[BarkingBad]

Type members:

• Very low contrast on the extends part - I changed the color, but maybe you find another color more suitable. In that case please make a PR or provide RGB code here.
• When clicking on a type member, the box the member is inside briefly expands before navigating off the page - Fixed

Value members:

• Types have very low contrast - Same as above
• Scaladoc groups value members into a few groups. The ones I found just looking around are: Constructors, abstract value members, concrete value members, deprecated value members. There are probably more. Scala3doc does some grouping, but would love some more here. - could you provide what groups should also be considered.
• Sort value members - right now they are sorted lexicographically
• Filtering the value members is kind of limited currently, as it also looks at the documentation for the method. Scaladoc also does this, but I'd love if just like the global search, if you searched for def map for examplke, it would only show methods named map. - @pikinier20, I am not sure if you have resolved that one. If so, please fill the checkbox.

Misc:

• Scala3doc is adding unneeded and confusing type lambdas to type signatures - we cannot fix it too easy as TASTY returns HKTypeLambdas even if you have plain type T[X]. I have recenlty merged bugfixes for typelambdas available here, but I think the whole concept should be discussed and rewritten, as for now we have mixed syntax. You can look at them here
• The first paragraph of the scaladoc of a class is smaller than the rest. - could you provide example? Otherwise, check it as resolved please.
• Some ": " values at the top of classes feels kind of unnatural at the moment. "Source: (source)" doesn't tell me that much. Scaladoc adds the name of the source where the class came from here. Companion object link also feels out of place here. It's not just metadata which is what I normally think of that section as, but an integral part of consuming the API of that class. I'd prefer to have it closer to the header, like scaladoc does. - we cannot fix that either, as we consume compiled classes from TASTY hence we don't know the original name of file. Companion objects are dealt by @pikinier20 I believe
• The list in the docs of Option seems to be ill formatted. - yes it is. It is related to its sources, where there is no empty line between list and text. Apparently flexmark forbides that (or it's a bug), becuase adding extra line everything works fine. We should investigate on that.
• Don't show annotations in the signature for class pages. They're already shown in the metadata section, and in many cases contain info that I don't care too much about like SerialVersionUID - the problem is, who would decide whether given annotation should be documented or not? Do we have to hardcode that list? Java and Kotlin has nice @MustBeDocumented meta annotations, which their doctools have a use. It would be nice if Scala would also define one. For now, I think we need to document all annotations.
• Port over the class, trait and object icons from Scaladoc. They really help to tell me what I'm looking at with a quick glance - @pikinier20 has already fixed that one
• I'd love some larger margins and more padding around the place. Paragraphs, member blocks and more. Just in general a tiny bit larger margins and more padding. - I am not good at aesthetic layout, I like the current one, but if you see something very wrong please provide what exactly should be change or feel free to make a proposal PR.
• Narrower pages. Scala3doc currently uses the full width of the screen. On wider screens that can become pretty tiresome to read. Scaladoc sets a limit of 1140px. I don't know if that's a good limit (I'd say so, although maybe something that reacts to screen size a bit more?) but I think some limit should be added. - we should discuss it in the futuer, as the old scaladoc has his navbar on the right next to the content of methods, types etc. whereas in new scaladoc we have navbar fixed to the left . Should the content be aligned to center with the given bound, so we would have navbar - empty space - content - empty space for higher resolutions, or empty space - navbar - content - emptysapce.
• Also some more notes on the sidebar that I just found. First off, you can scroll it horizontally. - I removed horizontal scroll. Yet there is problem for longer package or type names
• Also, if you expand something so that the sidebar goes from not being scrollable, to being scrollable, then the arrows move. Would be best if they didn't. If it's hard to make them not move, then maybe just show the scroll bar at all times? - fixed

[BarkingBad]

@Katrix I tried to address all of your requests, some I checked as resolved, some are just explained why I could not provide solution for now. Please assess which one would you like to implement and provide more information, and for those that are not valid for now please checkbox them as resolved.

[BarkingBad]

When the documentation is published via CI, the snapshot example should be available here https://scala3doc.virtuslab.com/pr-ux-fixes/index.html as a quick reference to above issues.

[Katrix]

Can't check the checkboxes, but I can go over what you've written at least 😄

The first paragraph of the scaladoc of a class is smaller than the rest: Seems to have been fixed.

Ill formatted Option: Tested the given source on a completely different thing of mine which uses Flexmark, and it rendered fine. It's probably either a bug, or a configuration option. I can see if I have time to look into that.

Showing class Annotations: That sounds like a wonderful solution honestly

Scaladoc member grouping: The groups the old Scaladoc does, which is not done currently here are: constructors, concrete and abstract value members
For abstract and concrete, see here how old Scaladoc does it compared to how it's done currently
https://scala3doc.virtuslab.com/pr-master/scala3/api/scala/concurrent/Promise.html
https://www.scala-lang.org/api/current/scala/concurrent/Promise.html

Should I open seperate issues for the remaining bigger items?
Name of source file
Documented annotations
Page width

[BarkingBad]

I'm working on part 2 of that issue.

• Ill formatted Option - I will investigate why it is ill-formatted then and hopefully will fix that.
• Scaladoc member grouping - I can add sections to abstract, concrete and constructors, however, as you can see, TASTY doesn't mark trait methods abstract by default if they don't provide implementation, it just adds Deferred flag. I have written to @abgruszecki so he can bring some insight to that case.
• Name of source file - I think I was too quick with my assumption. I think I can retrive source file name. I'll try to fix that too.
• Documented annotations - I would like to propose that change myself probably backed with PR if you don't mind
• Page width - I think we can continue in that thread, but if you feel there is a need for a separate issue you can go on.

[BarkingBad]

Current progress of issues

• Ill formatted Option - indeed we were suing KramDown syntax instead of CommonMark. I hope chagning to CommonMark flavour won't bring any regression.
• Scaladoc member grouping - I added temporarily sections for abstract and concrete members though I think it can probably be rollbacked in the future, as new scaladoc does some other
• Name of source file - fixed

[smarter]

Scaladoc member grouping

fyi, I opened an issue about this with some suggestions a while ago: #10893

[pikinier20]

I think all issues listed in this task are already adressed so I close it.