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.

Sign up for GitHub

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

Jump to bottom

docs(cache): add/change some comments for clarity #357

Merged
merged 1 commit into from
Jun 14, 2022
Merged

docs(cache): add/change some comments for clarity #357

merged 1 commit into from
Jun 14, 2022

Conversation

agilgur5
Copy link
Collaborator

Summary

  • Modify isDirty comment to use typedoc
  • Add a comment to specify that a condition is an invariant in init

Details

  • use typedoc for isDirty comment so that it actually appears in IDEs etc

    • and use @returns typedoc annotation for better specification
    • modify the comment a little for better grammar: 3 "or"s and no commas -> 1 "or" and commas
    • use more accurate terminology: "global types" -> "ambient types"
      • that's also more consistent in this codebase itself, where there's a legit function named checkAmbientTypes

  • in init, specify that the RollingCache error should never actually happen

    • I was a bit confused by when this would happen, then checked the constructor, and the answer is basically never: it's an invariant / redundant error-check
    • also add a new line for style consistency

@agilgur5
docs(cache): add/change some comments for clarity
b40d8fc 
- use typedoc for `isDirty` comment so that it actually appears in IDEs etc
  - and use `@returns` typedoc annotation for better specification
  - modify the comment a little for better grammar: 3 "or"s and no commas -> 1 "or" and commas
  - use more accurate terminology: "global types" -> "ambient types"
    - that's also more consistent in this codebase itself, where there's a legit function named `checkAmbientTypes`

- in `init`, specify that the `RollingCache` error should never actually happen
  - I was a bit confused by when this would happen, then checked the constructor, and the answer is basically never: it's an invariant / redundant error-check
  - also add a new line for style consistency
@agilgur5 agilgur5 added scope: docs Documentation could be improved. Or changes that only affect docs kind: internal Changes only affect the internals, and _not_ the public API or external-facing docs scope: cache Related to the cache labels Jun 11, 2022
@ezolenko ezolenko merged commit a3c2699 into ezolenko:master Jun 14, 2022
@agilgur5 agilgur5 deleted the docs-cache-typedoc-annotation branch July 2, 2023 21:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
kind: internal Changes only affect the internals, and _not_ the public API or external-facing docs scope: cache Related to the cache scope: docs Documentation could be improved. Or changes that only affect docs
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@agilgur5 @ezolenko