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: improve grammar & formatting, plus add TSConfig Reference links #375

Merged
merged 1 commit into from
Jul 6, 2022

Conversation

agilgur5
Copy link
Collaborator

@agilgur5 agilgur5 commented Jul 2, 2022

Summary

Improve grammar and formatting in the README, as well as add several TSConfig Reference links.

Details

  • improve grammar in several places

    • mostly add "the" and commas in several places where they were missing
      • and put a period or semicolon in a few places where there was a comma splice
      • for "deep merge", parens were used, whereas a colon is a better fit
    • consistently use "(see #x)", instead of sometimes using parens and other times using commas
      • also change "only if useTsconfigDeclarationDir" to "unless useTsconfigDeclarationDir" for clarity
        • have looked at this many times and thought something was unintuitive about this: useTsconfigDeclarationDir defaults to false after all
    • "typescript" -> "TypeScript" as a proper noun
    • "js" -> "JS" similarly
    • "es6" -> "ES6"
    • "rollup" -> "Rollup"
    • "rollup watch" -> "Rollup's watch mode"
    • "work directory" -> "working directory" (that's what the "w" stands for)
  • improve formatting in several places

    • split up paragraphs a bit more neatly as a single new line in Markdown is just rendered as a space
    • for tsconfig, objectHashIgnoreUnknownHack, and typescript, actually add a double new line
      • to break up the paragraph for better rendered readability
    • don't skip heading level for "Some compiler options" -- this should be an h3, not an h4
      • remove inconsistent period in one of the headings as well (and headings aren't normally supposed to have periods)
    • consistently use backticks when referencing plugin, tsconfig options, etc
    • consistently use 1 tab indent for plugin options' descriptions, instead of a few 2 tab indents
    • for "Requirements" section, use bullets instead having everything on one line
      • the way it was written seemed like they were intended to be on different lines, but a single new line in Markdown is just rendered as a space (per above)
        • bullets are a little better than just new lines as well
  • add TSConfig Reference links to several tsconfig options mentions

    • extends, declarationDir, declaration, declarationMap, and emitDeclarationOnly
      • also added the mention of extends in "chaining tsconfigs"

Misc

Been staring at the docs for a while and making edits slowly; finally wrote up a PR for it.
Also helps to look at the docs on NPM instead for a change of visuals to have less tunnel vision

- improve grammar in several places
  - mostly add "the" and commas in several places where they were missing
    - and put a period or semicolon in a few places where there was a comma splice
    - for "deep merge", parens were used, whereas a colon is a better fit
  - consistently use "(see #x)", instead of sometimes using parens and other times using commas
    - also change "only if `useTsconfigDeclarationDir`" to "unless `useTsconfigDeclarationDir`" for clarity
      - have looked at this many times and thought something was unintuitive about this: `useTsconfigDeclarationDir` defaults to `false` after all
  - "typescript" -> "TypeScript" as a proper noun
  - "js" -> "JS" similarly
  - "es6" -> "ES6"
  - "rollup" -> "Rollup"
  - "rollup watch" -> "Rollup's watch mode"
  - "work directory" -> "working directory" (that's what the "w" stands for)

- improve formatting in several places
  - split up paragraphs a bit more neatly as a single new line in Markdown is just rendered as a space
    - similar to my previous commit for `emitDeclarationOnly`
      - and apparently I missed two sentences in the "Declarations" section there too
  - for `tsconfig`, `objectHashIgnoreUnknownHack`, and `typescript`, actually add a double new line
    - to break up the paragraph for better rendered readability
  - don't skip heading level for "Some compiler options" -- this should be an h3, not an h4
    - remove inconsistent period in one of the headings as well (and headings aren't normally supposed to have periods)
  - consistently use backticks when referencing plugin, `tsconfig` options, etc
    - e.g. `tsconfig`, `include`, `exclude`, `node_modules`, etc
      - also, for `allowJs`, put the proper `**/node_modules/**/*` `exclude` as an example similar to the `**/*.js+(|x)`
        - as plain `node_modules` won't work as I've recently found out
  - consistently use 1 tab indent for plugin options' descriptions, instead of a few 2 tab indents
  - for "Requirements" section, use bullets instead having everything on one line
    - the way it was written seemed like they were intended to be on different lines, but a single new line in Markdown is just rendered as a space (per above)
      - bullets are a little better than just new lines as well

- add TSConfig Reference links to several `tsconfig` options mentions
  - `extends`, `declarationDir`, `declaration`, `declarationMap`, and `emitDeclarationOnly`
    - also added the mention of `extends` in "chaining tsconfigs"
@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 labels Jul 2, 2022
@ezolenko ezolenko merged commit 8f659a9 into ezolenko:master Jul 6, 2022
@agilgur5 agilgur5 added kind: dx Improvements to dev experience, e.g. error messages, logging, external-facing docs, etc and removed kind: internal Changes only affect the internals, and _not_ the public API or external-facing docs labels Jul 22, 2022
@agilgur5 agilgur5 deleted the docs-grammar-format branch July 2, 2023 21:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind: dx Improvements to dev experience, e.g. error messages, logging, external-facing docs, etc scope: docs Documentation could be improved. Or changes that only affect docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants