Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

library references should be URIs, not the library name #1658

Closed
kevmoo opened this issue Apr 2, 2018 · 14 comments · Fixed by #3552
Closed

library references should be URIs, not the library name #1658

kevmoo opened this issue Apr 2, 2018 · 14 comments · Fixed by #3552
Assignees
Labels
customer-google3 Issues originating from or important to Angular P2 A bug or feature request we're likely to work on type-enhancement A request for a change that isn't a bug

Comments

@kevmoo
Copy link
Member

kevmoo commented Apr 2, 2018

See
https://pub.dartlang.org/documentation/angular/5.0.0-alpha+9/index.html

screen shot 2018-04-02 at 10 39 52 am

Doesn't help

Should be

angular.dart
builder.dart
core.dart
di.dart
experimental.dart
security.dart

These are the actual files I'd import.

...and more painfully
https://pub.dartlang.org/documentation/angular_components/0.9.0-alpha+9/index.html

In this case, there are many libraries named module – no way to tell them apart.

Better to have long URIs than ambiguous names...

@kevmoo kevmoo added type-enhancement A request for a change that isn't a bug P2 A bug or feature request we're likely to work on user feedback labels Apr 2, 2018
@jcollins-g
Copy link
Contributor

Yeah, that's a problem.

We should remove all usages of library names in dartdoc. I think this is likely the main thing blocking dart-lang/sdk#32738; most other pieces of the ecosystem either don't care about the library name at all or don't use it for important things.

@kevmoo
Copy link
Member Author

kevmoo commented Mar 20, 2023

So I went through googleapis and got rid of pointless library XYZ; names - google/googleapis.dart@a4e0b03 – cool 2.19 feature @srawlins !

Guess what?

Before:
image

After:
image

We should really fix this!

@kevmoo
Copy link
Member Author

kevmoo commented Mar 20, 2023

FYI: all of those v1 things map to compute/v1.dart, ml/v1.dart etc etc

@devoncarew
Copy link
Member

Here's an example of one of the source files:

https://github.com/google/googleapis.dart/blob/master/generated/googleapis/lib/abusiveexperiencereport/v1.dart

That's currently inferring v1 as the label for the left nav, but I gather (from the issue title) that we want something more like abusiveexperiencereport/v1.dart.

@srawlins
Copy link
Member

Whoa. Mega cringe.

@jcollins-g
Copy link
Contributor

What if the import URIs were available via mouseover and on the library pages themselves, and we started warning for duplicate library names in the same package? No matter what compressed form we choose for the left sidebar there are going to be cases where the user will want to override that -- and there already is a way to do that, the library foo; statement. It's true that it has been deemphasized but I doubt it's going to go away entirely as long as part files exist. We might as well make use of it for its ability to label libraries.

@natebosch
Copy link
Member

but I doubt it's going to go away entirely as long as part files exist.

We also prefer that part files refer to the library they are part of by URI and not library name.
https://dart.dev/guides/language/effective-dart/usage#do-use-strings-in-part-of-directives

@srawlins
Copy link
Member

@kevmoo I have a WIP that looks like this, WDYT?

Screenshot 2023-10-20 at 8 43 51 AM Screenshot 2023-10-20 at 8 44 08 AM

This does cause some library names to be truncated with a ..., but I can fix that as well by making the left panel horizontally scrollable, for #1043. (I think making the names wrap lines would make it an unreadable mess.)

@natebosch
Copy link
Member

I can fix that as well by making the left panel horizontally scrollable

Good plan. How about we also save a few characters of space and strip the .dart?

I think making the names wrap lines would make it an unreadable mess.

+1

@srawlins
Copy link
Member

I guess I'm conflating two issues, but adding ".dart" solves #1000 as well.

I could use, for example, v1/admob in the sidebar, and v1/admob.dart in the heading?

@devoncarew
Copy link
Member

I wonder if very long library paths aren't the exception rather than the rule, and we couldn't just get away with truncation + having the full path in a tooltip? It would save giving the left nav more space - which would eat into other screen real estate - or making it horizontally scrollable, which I think would overall hinder usability.

@srawlins
Copy link
Member

Yeah a tooltip is a good idea too. Probably better UX.

@natebosch
Copy link
Member

I could use, for example, v1/admob in the sidebar, and v1/admob.dart in the heading?

I think that could work. It would also be OK to retain the .dart in the sidebar - but the repetition is somewhat distracting IMO.

@kevmoo
Copy link
Member Author

kevmoo commented Oct 23, 2023

Since EVERY import will end in .dart dropping it SGTM!

Maybe include it in the tooltip?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
customer-google3 Issues originating from or important to Angular P2 A bug or feature request we're likely to work on type-enhancement A request for a change that isn't a bug
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants