Dart 3 class modifiers should be clearly visible in dartdocs

[mit-mit]

Dart 3 apps new class modifiers (dart-lang/language#2242), and the core libraries have been updated to many cases to use these. For example, the platform class in dart:io is now abstract final.

In the current DartDocs it's very hard to see these modifiers (e.g. platform). They are shown just textually near the top:

I'd like to suggest the following improvements to make class modifiers more clear:

1. Show capability chips after the class name (similar to the chips we show on API members in the rest of the page):

2. On generative constructors, show them as now available (e.g. using strikethrough text) with capability chips detailing why. From @lrhn the combinations where the constructor isn't available are: a) sealed, b) abstract final, and c) abstract interface).

[mit-mit]

cc @srawlins @jcollins-g, I think this is a pretty important change for Dart 3. wdyt?

[mit-mit]

We should probably also have an abstract annotation on constructors in general to clarify that they can only be called from subclasses?

[srawlins]

In the current DartDocs it's very hard to see these modifiers (e.g. platform). They are shown just textually near the top:

IIRC this was an intentional decision. I don't believe we consulted UX at the time (CC @InMatrix), but some subset of the team agreed that these did not need to be prominent on the page (as abstract is not prominent).

I think we strayed away from the chips idea because @InMatrix has some students who pointed out that the chips are very prominent to the point of distraction in other pages, like this:

But in your suggestion, there wouldn't be too many chips cluttering up the page next to the class (max of... 3?) so it could probably work.

[jcollins-g]

I had considered this, but this was also left out because there wasn't much time for a UX design pass when we needed to implement and ship this and given the historical handling of abstract, this seemed reasonable. This is still the case.

[InMatrix]

Showing capability chips after the class name seems OK, since there aren't other chips in that part of the page. If we do that, we can drop "abstract final` from the breadcrumb to make it easier to read.

[jcollins-g]

@InMatrix sounds reasonable. Should chips be displayed on the library pages as well with each class listed?

[mit-mit]

I don't think the breadcrumb is even close to visible enough. I only found it as I did a CTRL-F search for the word final.

[InMatrix]

Should chips be displayed on the library pages as well with each class listed?

It depends on what kind of user need, if any, displaying those chips on the library pages might serve. For example, do we anticipate users to look for classes with specific capabilities on a library page such as https://api.dart.dev/beta/3.0.0-417.2.beta/dart-io/dart-io-library.html? Will they decide to click into a class page based on whether that class is abstract or not? I'd not show those chips on the library pages until we identify concrete value they might provide to the user.

[mit-mit]

The main reason to show the modifier chips is to communicate things that you can't do (like instantiate an abstract class). I think it might be sufficient to show that on the individual class pages.

[jcollins-g]

I'll take a look at adding the chips and replacing the words in the breadcrumb with those. Not currently planning to cherry pick this however.

[mit-mit]

Why not? This seems like a major usability trap. There is no way to see in the current docs what the class capabilities are (the breadcrump is really insufficient).