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(core): Add TSDocs annotations to @urql/core exported APIs #2962

Merged
merged 18 commits into from
Mar 7, 2023

Conversation

kitten
Copy link
Member

@kitten kitten commented Feb 17, 2023

Summary

This adds TSDoc annotations to all exported APIs.
Generally, the style guide followed is:

  • The short description will not contain links
  • @param and @returns tags are generally added and contain links
  • The remarks will contain further functionality if this isn't obvious from @param or @returns tags
  • All notes to implementors/users are marked further with Hint:
  • @see links are added to refer to important, otherwise not linked, parts of the TSDocs or web links
  • Examples are only added when they illustrate a non-obvious usage pattern
  • @throws is added if it's not obvious that an API can explicitly throw an error

This is the first PR that makes use of the build changes from #2956, which bundles all d.ts typings files, which gives a better TSDocs experience.

Since we weren't sure whether slowly adding TSDocs to all our packages is worthwhile (it’s extremely time intensive) we ran polls to validate it:

At the time of creation of this PR,

  • 42.4% voted that detailed TSDocs have a highly positive impact
  • and 39.4% voted that it had a medium (situational impact)
  • the minority voted that it only has a low impact

Set of changes

  • Add TSDocs to all @urql/core exports
  • Hide accidentally exposed fallbackExchangeIO export (not considered breaking/minor since it's unlikely to be used and was never meant to be exposed)

@kitten kitten requested a review from JoviDeCroock February 17, 2023 17:24
@kitten kitten force-pushed the docs/tsdocs-core branch from b1f362f to e09e558 Compare March 7, 2023 15:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants