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

[docs] API browser and "see" JSDoc tag support #2041

Merged
merged 12 commits into from
Feb 7, 2018
Merged

Conversation

giladgray
Copy link
Contributor

@giladgray giladgray commented Jan 25, 2018

Fixes #817, Fixes #2020

(not really a breaking change, but we want to get this in for 2.0)

Changes proposed in this pull request:

Known Typescript members are now links! Clicking such a link opens an API Browser dialog with full information about that member, and you can link around to other related members, or browser the entire set of known members.

Reviewers should focus on:

  • the UI here is pretty rough. what's the minimal feature set to make this passable?

Screenshot

api-browser

@blueprint-bot
Copy link

fix some docs issues discovered through browsing

Preview: documentation | landing | table

@blueprint-bot
Copy link

closed browser by default

Preview: documentation | landing | table

@adidahiya
Copy link
Contributor

looks passable enough for now.

@blueprint-bot
Copy link

visual polish for the API browser

Preview: documentation | landing | table

@adidahiya
Copy link
Contributor

I don't really understand how the left sidebar is useful. Why would you want to browse to other interfaces by name? Wouldn't you always just click on them from the docs? This is a weird additional navigation layer on top of the docs and I think it's confusing.

Copy link
Contributor

@adidahiya adidahiya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see above

@llorca
Copy link
Contributor

llorca commented Jan 26, 2018

yeah, right now you click one from the component docs. we had plans on providing a dedicated button/page for the API docs only, which is why this dialog has a search and a list of all interfaces

@llorca
Copy link
Contributor

llorca commented Jan 26, 2018

Do we display empty interfaces on purpose?
image

@adidahiya
Copy link
Contributor

Also string unions like IconName could use some visual work

@llorca
Copy link
Contributor

llorca commented Jan 26, 2018

word. maybe we just truncate for now. also noticed that @blueprintjs/icons doesn't link anywhere:
image

@blueprint-bot
Copy link

add div wrapper around interface tables

Preview: documentation | landing | table

@adidahiya
Copy link
Contributor

adidahiya commented Jan 29, 2018

Hmm I'm still not sure about the dialog design... what if it was a sidebar on the right of the whole docs app?

a few issues:

  • this interface is blank
    image
  • icon name overflows the dialog and doesn't scroll

@giladgray
Copy link
Contributor Author

Dialog is cheap design & implementation. Adding a third column is expensive on both sides.

Will fix those issues.

@blueprint-bot
Copy link

add support for indexSignature

Preview: documentation | landing | table

@adidahiya
Copy link
Contributor

why is this a breaking change?

@adidahiya adidahiya changed the title [docs] API browser! [docs] API browser and "see" JSDoc tag support Feb 7, 2018
@adidahiya adidahiya merged commit 1d2ec47 into develop Feb 7, 2018
@adidahiya adidahiya deleted the gg/api-browser branch February 7, 2018 14:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants