Graphiql: Show inline field description in documentation explorer

[OlegIlyenko]

At the moment fields look like this:

In contrast, enum values, for instance, which have an inline documentation for all of the values:

I find it very helpful to see the documentation for all of the fields or enum values in one view, especially when I'm trying to learn new API.

So my suggestion is display descriptions inline for fields as well:

This raises a concern: I guess field descriptions tend to have much more information in them than an enum values. I can also imagine putting an example code snippet in the description. Maybe in this case we can truncate the description and show only a first paragraph or something along these lines?

I would be really interested to know your opinion on this :)

[asiandrummer]

@OlegIlyenko - I think what you have in mind is great. We can also do an expand/collapse style of inlined descriptions, but showing the first paragraph (or a sentence or two really) if it gets too long sounds like a great start.

Something to keep in mind is that DocExplorer doesn't limit the number of fields to be shown in the div, so if a type defines some large number of fields then the browser might suffer. Obviously this issue exists even without the description texts, and we should probably limit the number of field definitions to be shown in the type documentation to a reasonable number, but this sounds like a whole another issue to track.

@leebyron and I were talking about something similar to this (in context of deprecationReason) - cc-ing since I'd love to get Lee's input as well ;)

[hepin1989]

Could we have an button aside the field name,and follow with the first line of the description，after we click the + button,it show all the description,and display a -？

eg:

field:Int +
description first line.

and after click the + button

field:Int -
description first line.this is the follow words ...

[joelgriffith]

I have an MVP at this, simple expands a section when you hover over it (it's not very slick). Otherwise we have to keep track of expansion state which gets a little noisy:

[joelgriffith]

Here's another pass, this one I prefer more over the last

[asiandrummer]

@joelgriffith what you have is so awesome - thanks for taking your time to help out. I personally like the second one, except that it still doesn't resolve the original concern 100% and the user has to click the arrow(s) individually to show the descriptions. Maybe Show All button could be useful?

[joelgriffith]

Yeah, would an Expand Descriptions or something similar next to the Fields header work? I could also split the difference and show the first line of text (similar to implementation 1), and then expand all when the expand link is clicked?

[asiandrummer]

I think showing the first line of text might get a bit redundant - we can start with Expand Descriptions idea we have and see how that feels. How does that sound?

[OlegIlyenko]

@joelgriffith Thanks a lot for looking into it and sharing your ideas!

Generally I think the idea to expand field is pretty interesting. Maybe we can add "Expand All"/"Collapse All" toggle in the "Fields" header?

Now that I think about it, if we already allow to expand fields' description, then maybe we can change the UX a bit:

• When user clicks on the field, instead of changing the view to a field page, we just expand the description
• This will not only show the full description, but also all of the field arguments with their descriptions
• At the end of expanded description we can put a link to a full field view - the one that user correctly gets when she clicks the field name. This, kind of, changes the default for this action.
• In a collapsed state, one can still see the first paragraph of a description (possibly truncated)

I these docs represent this ides pretty closely (try to click on the method descriptions): http://www.scala-lang.org/api/current/scala/collection/immutable/HashMap.html

WDYT?

[joelgriffith]

I'm on board for that, could be considered a breaking change from a user perspective, but it fairly easy enough to implement

[andheiberg]

@joelgriffith are you still considering sending a PR for this?

[joelgriffith]

Definitely, was mostly waiting to hear back from maintainers at this point before putting in the work. I have some code that I could dust off on this.

[wincent]

At this point we have a few competing ideas:

• Show inline.
• Show inline, but truncated if too long.
• Expand on hover.
• Expand on click.

And a few combinations/nuances overlaid, such as "expand/collapse all", pagination, and so on.

In the abstract, I think the way to move forward is to try building a few of them and take them for a test drive.

Personally and concretely however, I think we can rule out hover as a UI anti-pattern. I'm also not a huge fan of expand-on-click, given that the original motivation was to give an overview at a glance without requiring a heavier-weight interaction, and additionally because it would be splitting the doc explorer paradigm into two models (one where clicking navigates to a new view, and another where it modifies an existing view inline; I think it's better to keep things pure and stick to a single model).

So my vote would be to build an initial cut that shows inline. If the descriptions wind up being too long in practice, only then would I look at adding a way to collapse/expand them. And finally, the very last thing I'd do is look at pagination.

[joelgriffith]

Here's a WIP on this, still need to ellipses-ify the overflowing text. Thoughts on this?

[wincent]

That looks like a good start to me, @joelgriffith. Once you get the ellipsis overflow working, how about sending a PR for us to poke around in? (Also, will solicit feedback from person with actual design-talent; I'm just a taste-challenged engineer.)

[joelgriffith]

@wincent https://github.com/graphql/graphiql/pull/322. npm run dev includes a field with a longer description for your testing

[bdougie]

I think this is done. Right @acao?

[acao]

yes it is, thank you @bdougie !