Page MenuHomePhabricator

Make the visibility indicators clearer ("private", "protected", etc)
Closed, ResolvedPublic

Description

Setup instructions

See https://phabricator.wikimedia.org/project/profile/3689/

Skills

HTML◾️◾️◽️◽️◽️
CSS◾️◾️◾️◾️◽️
Design◾️◾️◾️◾️◽️

In T187672 @Krinkle said:

Alignment of method names vs visibility indicators. When interacting with the page and searching and jumping between methods, I found myself getting confused multiple times by the visibility indicator in front of the method name. Some form of visual aid and alignment would help here, I think. The JSDuck equivalent did a lot here. It separated the indicator from the heading by encapsulating the indicator in a bubble, it also used a different text style (all-caps), text size (smaller), and colour (purple/orange vs blue). Doing all of these is probably overkill, but we may need one or two of these compared to now. Perhaps move the indicator to after the signature, and perhaps right-aligned and/or using a third color (in addition to grey and blue), or a different wrapping (e.g. square brackets). I expect you'll have better ideas here :)

StateCurrentProposed
Closed
Screen Shot 2018-11-22 at 3.03.47 PM.png (968×834 px, 122 KB)
Screen Shot 2018-11-22 at 3.16.23 PM.png (1×1 px, 130 KB)
Open
Screen Shot 2018-11-22 at 3.13.39 PM.png (804×1 px, 165 KB)
Screen Shot 2018-11-22 at 3.18.04 PM.png (1×1 px, 220 KB)

Event Timeline

Prtksxna renamed this task from Make it the visibility indicators clearer to Make the visibility indicators clearer.Oct 24 2018, 4:38 AM
Krinkle renamed this task from Make the visibility indicators clearer to Make the visibility indicators clearer ("private", "protected", etc).Sep 9 2020, 12:25 PM

I don't see any visibiliy indicators in the screenshots, and hte before/after screenshots seem identical to me.

Screenshot 2023-08-24 at 11.58.27.png (950×519 px, 66 KB)

I do think this indentation jumping around is distracting. I think it would be nicer to have bubbles behind the function signature, or to have bubbles just above the signature perhaps.

Change 982153 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[jsdoc/wmf-theme@master] Make attributes (static, protected) more visually distinct

https://gerrit.wikimedia.org/r/982153

AnneT changed the task status from Open to In Progress.EditedDec 11 2023, 7:56 PM
AnneT claimed this task.
AnneT subscribed.

In my patch, I styled the indicators to look like chips/tags. I also used a yellow background and border color for protected and red for private. Thoughts?

Screenshot 2023-12-11 at 2.42.40 PM.png (480×1 px, 101 KB)

Screenshot 2023-12-11 at 7.39.39 PM.png (160×916 px, 19 KB)

What do we think of the colors? Are there other indicators we should account for? @chainable doesn't work with JSDoc at the moment (see T214096).

I think this is a lot better @AnneT .

I do wonder if we should move the chips to their own line. Maybe above the function name ? That might require redoing that entire block with the hide/show with some flex box magic however.

Are there other indicators we should account for?

I also found: nullable https://doc.wikimedia.org/TimedMediaHandler/master/js/js/MediaElement.html

Thanks @TheDJ!

I looked through some more repositories and also found inner and constant. I think the design decision here is: which attributes, if any, should be distinguished via different colors? Just protected and private? I've also played around with making static look more...static:

Screenshot 2023-12-12 at 10.36.16 AM.png (738×1 px, 127 KB)

But I'm not sure it really needs to be distinct from other attributes like nullable:

Screenshot 2023-12-12 at 10.37.42 AM.png (470×1 px, 74 KB)

I do wonder if we should move the chips to their own line. Maybe above the function name ? That might require redoing that entire block with the hide/show with some flex box magic however.

I gave this a shot - it makes the tags much more prominent, but increases the space taken up by each accordion section. What do you think?

Screenshot 2023-12-12 at 10.48.49 AM.png (902×1 px, 131 KB)

I also tried putting the tags on the end of the line:

Screenshot 2023-12-12 at 10.37.03 AM.png (572×1 px, 81 KB)

screenshot of static pill in jsduck

Screenshot 2023-12-12 at 17.00.34.png (398×546 px, 48 KB)

@TheDJ nice - so perhaps it is helpful to have static be distinguished from other things.

@egardner made the following suggestions:

  • Put the tags either above or after the signature so the member/method names are more easily scannable
  • Make static, protected, and private the same color. This highlights them against the other attributes, but doesn't distinguish them from each other, which makes sense (using warning and error colors for them gave them unnecessary meaning)

I've made these updates in my patch, which now results in this:

image.png (750×1 px, 118 KB)

@egardner made the following suggestions:

  • Put the tags either above or after the signature so the member/method names are more easily scannable
  • Make static, protected, and private the same color. This highlights them against the other attributes, but doesn't distinguish them from each other, which makes sense (using warning and error colors for them gave them unnecessary meaning)

I've made these updates in my patch, which now results in this:

image.png (750×1 px, 118 KB)

Thanks, Anne. I think we can always introduce further refinements later but I believe this is a good update for now.

Change 982153 merged by jenkins-bot:

[jsdoc/wmf-theme@master] Make attributes (static, protected) more visually distinct

https://gerrit.wikimedia.org/r/982153

We've gone with the design in my last comment for now; please open a new task if you'd like to suggest changes or improvements!

apaskulin subscribed.

Released in 0.0.10