DXR Provide user guidance information on all pages

NEW
Unassigned

Status

Webtools
DXR
5 years ago
4 years ago

People

(Reporter: espressive, Unassigned)

Tracking

Firefox Tracking Flags

(Not tracked)

Details

(Reporter)

Description

5 years ago
Provide user guidance information on all pages but, the visibility of this information should be entirely user driven.

See the concept UI for this change on https://wiki.mozilla.org/Webtools/DXR_User_Research#Front_Page_Mock

Comment 1

5 years ago
the front page mock looks good. I think we use implement this. Any plan on proceeding with this?
I'm actually hoping to get rid of the front page altogether and obviate the need for ubiquitous documentation with query-by-example. See https://wiki.mozilla.org/DXR_UI_Refresh, and please add your comments.

Comment 3

4 years ago
There are no actual examples presented anywhere on the site. It's rather mysterious for a new user. The closest that exists now is picking a filter and trying to make it return useful results. This might be the wrong approach because it's really time-consuming and frustrating. The user has to imagine some expected payoff rather than seeing someone else's payoff from using the tool.
I do have a few limited examples in the Filters menu. Those clearly being insufficient, what would you like to see? Queries with sample results? A description of the query language itself, e.g. http://dxr.readthedocs.org/en/latest/use.html#querying? I do want to add more online help to DXR if I can't make the UI self-evident, so your input is most welcome.

Comment 5

4 years ago
For the Mozilla DXR instance, it would be great if the examples were useful in the context of the codebase itself. For example, wanting to see all the platform specific subclasses of gfxFontShaper, you would probably do 'derived:gfxFontShaper', right? But for finding overrides of methods in that class, would you use derived+function+overrides, or would you use type+function+overridden? If there's an real-world example for each filter plus a one-sentence comment, that would make it really clear what the simplest use of each filter is. It would be cool if clicking on the example will copy it into the search bar and show the results of the query. That scaffolds the user's experimenting with live results.

Side note, for things that select types, members, functions, etc it's not quite clear how the filters combine. Is it a union of results for each filter? If not, does it compose like CSS? Can you query functions-of-queried-classes?
Hmm, codebase-specific examples. I like the start-here-and-then-customize of that for new users. I'd have to figure out where to store that, of course. Right now the codebase has no tree-specific stuff in it, but we could jam it in the config somewhere. Even better would be if users could easily contribute back to it.

It also sounds like more description is needed for each filter, beyond the succinct descriptions in the Filters menu. Are the descriptions there useless to you, or is it mostly a matter of making the examples real-world?

As for filter combinations, there aren't any practically useful ones yet beyond combining "path:" and "ext:" with things. In the next major revision of DXR, filters will AND together strictly by line, so at least behavior will be predictable (and there may be a few useful cases that fall out). After that, I'm considering a number of inter-filter operators like the IN described in https://wiki.mozilla.org/DXR_Query_Language_Refresh#More_Explicit_Operators. Then at least you can specify what you want without DXR having to guess (and you having to guess what it's guessing).

Finally, you ask a harder question than you probably realize with the "finding overrides of methods in that class" question. That's tricky on the back end because you're spanning two levels of relationships (methods-of, overrides-of) from your static argument (the class). To exacerbate matters, we're currently converting away from a relational store. How frequently do you do overrides-of-methods-of? How often do you do other similarly indirect queries? I can think of a couple ways to make it possible: (1) special-case that specific kind of query, and lay down things like override-of-method-of-class:SomeClass in ES at index time or (2) more generally support indirect queries by doing joins on the app side (first find methods of SomeClass, then find overrides of them as a multi-query or something). Both will require nontrivial effort.

Thanks again for your helpful perspective!
Incidentally, if we do end up doing application-side joins at some point, we can walk around ES aliases, ask it directly which index is current, and make sure we query that one for the duration of the request. That will neatly equate to a serializable isolation level.
You need to log in before you can comment on or make changes to this bug.