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

Show inline field description in documentation explorer #169

Closed
OlegIlyenko opened this issue Sep 19, 2016 · 17 comments
Closed

Show inline field description in documentation explorer #169

OlegIlyenko opened this issue Sep 19, 2016 · 17 comments

Comments

@OlegIlyenko
Copy link
Contributor

At the moment fields look like this:

graphiql-fields

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

graphiql-enum-description

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:

graphiql-fields-description

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
Copy link
Contributor

@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 ;)

@He-Pin
Copy link

He-Pin commented Sep 20, 2016

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
Copy link

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:

doc-expansion

@joelgriffith
Copy link

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

@asiandrummer
Copy link
Contributor

@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
Copy link

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
Copy link
Contributor

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
Copy link
Contributor Author

@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
Copy link

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

@andheiberg
Copy link

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

@joelgriffith
Copy link

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
Copy link
Contributor

wincent commented Jan 31, 2017

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
Copy link

screen shot 2017-02-09 at 11 21 23 am

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

@wincent
Copy link
Contributor

wincent commented Feb 9, 2017

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
Copy link

@wincent #322. npm run dev includes a field with a longer description for your testing

acao pushed a commit to acao/graphiql that referenced this issue Jun 1, 2019
acao pushed a commit to acao/graphiql that referenced this issue Jun 5, 2019
@bdougie
Copy link

bdougie commented May 29, 2020

I think this is done. Right @acao?

@acao
Copy link
Member

acao commented Dec 11, 2020

yes it is, thank you @bdougie !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

8 participants