Clean up capitalization, parentheses, and phrasing in docs (microsoft…

…#2817)

I updated library documentation links
(https://microsoft.github.io/typespec/libraries =>
https://typespec.io/docs/libraries), should I update the other
https://microsoft.github.io links as well?

.changeset/gorgeous-spiders-crash.md

@@ -0,0 +1,31 @@
+---
+"@typespec/prettier-plugin-typespec": patch
+"@typespec/eslint-config-typespec": patch
+"@typespec/eslint-plugin": patch
+"@typespec/internal-build-utils": patch
+"tmlanguage-generator": patch
+"@typespec/html-program-viewer": patch
+"@typespec/playground-website": patch
+"@typespec/bundle-uploader": patch
+"typespec-vscode": patch
+"@typespec/best-practices": patch
+"@typespec/library-linter": patch
+"@typespec/json-schema": patch
+"typespec-vs": patch
+"@typespec/playground": patch
+"@typespec/versioning": patch
+"@typespec/compiler": patch
+"@typespec/openapi3": patch
+"@typespec/protobuf": patch
+"@typespec/bundler": patch
+"@typespec/openapi": patch
+"@typespec/samples": patch
+"@typespec/website": patch
+"@typespec/http": patch
+"@typespec/rest": patch
+"@typespec/spec": patch
+"@typespec/tspd": patch
+"@typespec/e2e": patch
+---
+
+Clean up docs

CONTRIBUTING.md

@@ -296,7 +296,7 @@ that gets produced.
 ## Trigger TypeSpec Playground Try It build
 
 For contributors of the repo the build will trigger automatically but for other's forks it will need a manual trigger from a contributor.
-As a contributor you can run the following command to trigger the build and create a typespec playground link for this PR.
+As a contributor you can run the following command to trigger the build and create a TypeSpec playground link for this PR.
 
 ```
 /azp run TypeSpec Pull Request Try It

README.md

@@ -23,11 +23,11 @@ You can try TypeSpec on the web without installing anything.
 
 ## Getting Started
 
-For documentation for TypeSpec language, see https://microsoft.github.io/typespec.
+For documentation on the TypeSpec language, see https://microsoft.github.io/typespec.
 
 ### Using Docker
 
-[See docker documentation](./docker)
+[See Docker documentation](./docker)
 
 ### Using Node & Npm
 
@@ -41,7 +41,7 @@ For documentation for TypeSpec language, see https://microsoft.github.io/typespe
 
    It is recommended to have npm 7+. To update npm run `npm install -g npm`
 
-2. Install TypeSpec compiler and libraries:
+2. Install the TypeSpec compiler and libraries:
 
 ```bash
    npm init -y
@@ -66,8 +66,8 @@ If you do not wish to install the compiler globally with `-g` flag, you will nee
 
 2. Initialize a TypeSpec project.
 
-   - Run `tsp init` > Select `Generic Rest API` template with `@typespec/rest` and `@typespec/openapi3` libraries checked.
-   - Run `tsp install` to install node package dependencies.
+   - Run `tsp init` > Select `Generic REST API` template with `@typespec/rest` and `@typespec/openapi3` libraries checked.
+   - Run `tsp install` to install Node package dependencies.
 
 3. Open the folder in your editor and edit `main.tsp`
 
@@ -132,7 +132,7 @@ TypeSpec provides an auto-formatter to keep your specs clean and organized.
 ```bash
 tsp format <patterns...>
 
-# Format all the files in the current directory with the typespec extension.
+# Format all the files in the current directory with the TypeSpec extension.
 tsp format **/*.tsp
 
 # Exclude certain patterns. Either use `!` prefix or pass it via the `--exclude` or `-x` option.

docker/readme.md

@@ -1,4 +1,4 @@
-# Use typespec via docker
+# Use TypeSpec via Docker
 
 Image: `azsdkengsys.azurecr.io/typespec`
 
@@ -12,10 +12,10 @@ Tags:
 docker run \
   -v "${pwd}:/wd" --workdir="/wd" \
   -t azsdkengsys.azurecr.io/typespec \
-  # ... typespec args ...
+  # ... TypeSpec args ...
 ```
 
-**For usage in powershell replace `\` with `` ` ``**
+**For usage in PowerShell replace `\` with `` ` ``**
 
 ### Install dependencies
 

docs/extending-typespec/basics.md

@@ -11,14 +11,14 @@ This document assumes you will be using [TypeScript](https://typescriptlang.org)
 
 ## Prerequisites
 
-You will need both node and npm installed. Additionally, if you intend to develop multiple libraries together, you will likely want to establish a monorepo as this will make developing the libraries in tandem much easier. TypeSpec itself uses [rush.js](https://rushjs.io/).
+You will need both Node and npm installed. Additionally, if you intend to develop multiple libraries together, you will likely want to establish a monorepo as this will make developing the libraries in tandem much easier. TypeSpec itself uses [rush.js](https://rushjs.io/).
 
 ## Setup with templates
 
 Available templates:
 
 ```bash
-# Create a TypeSpec library(Decorators & Linters) with TypeScript enabled.
+# Create a TypeSpec library (Decorators & Linters) with TypeScript enabled.
 tsp init --template library-ts
 
 # Create a TypeSpec emitter with TypeScript enabled.
@@ -29,9 +29,9 @@ tsp init --template emitter-ts
 
 The following is a high level overview of the contents of a TypeSpec package. These files are explained in more detail in the subsequent sections.
 
-- **dist/index.js** - the main file for your node library
+- **dist/index.js** - the main file for your Node library
 - **lib/main.tsp** - the main file for your TypeSpec types (optional)
-- **src/index.ts** - the main file for your node library in TypeScript
+- **src/index.ts** - the main file for your Node library in TypeScript
 - **src/lib.ts** - the TypeSpec library definition file
 - **package.json** - metadata about your TypeSpec package
 
@@ -49,9 +49,9 @@ Run the following commands:
 > npm init
 ```
 
-After filling out the wizard, you will have a package.json file that defines your typespec library.
+After filling out the wizard, you will have a package.json file that defines your TypeSpec library.
 
-Unlike node libraries which support CommonJS (cjs), TypeSpec libraries must be Ecmascript Modules. Open your `package.json` and add the following top-level configuration key:
+Unlike Node libraries which support CommonJS (cjs), TypeSpec libraries must be ECMAScript Modules. Open your `package.json` and add the following top-level configuration key:
 
 ```jsonc
   "type": "module"
@@ -71,7 +71,7 @@ See [dependency section](#defining-dependencies) for information on how to defin
 
 ### c. Define your main files
 
-Your package.json needs to refer to two main files: your node module main file, and your TypeSpec main. The node module main file is the `"main"` key in your package.json file, and defines the entrypoint for your library when consumed as a node library, and must reference a js file. The TypeSpec main defines the entrypoint for your library when consumed from a TypeSpec program, and may reference either a js file (when your library doesn't contain any typespec types) or a TypeSpec file.
+Your package.json needs to refer to two main files: your Node module main file, and your TypeSpec main. The Node module main file is the `"main"` key in your package.json file, and defines the entrypoint for your library when consumed as a Node library, and must reference a JS file. The TypeSpec main defines the entrypoint for your library when consumed from a TypeSpec program, and may reference either a JS file (when your library doesn't contain any TypeSpec types) or a TypeSpec file.
 
 ```jsonc
   "main": "dist/src/index.js",
@@ -150,7 +150,7 @@ You can then run `npm run build` or `npm run watch` to build or watch your libra
 
 ### h. Add your main TypeSpec file
 
-Open `./lib/main.tsp` and import your JS entrypoint. This ensures that when typespec imports your library, the code to define the library is run. In later topics when we add decorators, this import will ensure those get exposed as well.
+Open `./lib/main.tsp` and import your JS entrypoint. This ensures that when TypeSpec imports your library, the code to define the library is run. In later topics when we add decorators, this import will ensure those get exposed as well.
 
 ```typespec
 import "../dist/index.js";
@@ -174,8 +174,8 @@ model Person {
 
 Defining dependencies in a TypeSpec library should be following these rules:
 
-- use `peerDependencies` for all TypeSpec libraries(+ compiler) that you use in your own library/emitter
-- use `devDependencies` for the other typespec libraries used only in tests
+- use `peerDependencies` for all TypeSpec libraries (+ compiler) that you use in your own library/emitter
+- use `devDependencies` for the other TypeSpec libraries used only in tests
 - use `dependencies`/`devDependencies` for any other packages depending if using in library code or in test/dev scripts
 
 TypeSpec libraries are defined using `peerDependencies` so we don't end-up with multiple versions of the compiler/library running at the same time.
@@ -204,7 +204,7 @@ TypeSpec libraries are defined using `peerDependencies` so we don't end-up with
 
 ## 4. Testing your TypeSpec library
 
-TypeSpec provides a testing framework to help testing libraries. Examples here are shown using node built-in test framework(Available node 20+) but any other JS test framework can be used that will provide more advanced features like vitest which is used in this project.
+TypeSpec provides a testing framework to help testing libraries. Examples here are shown using Node.js's built-in test framework (available in Node 20+) but any other JS test framework can be used that will provide more advanced features like vitest which is used in this project.
 
 ### a. Add devDependencies
 
@@ -233,7 +233,7 @@ export default defineConfig({
 
 ### b. Define the testing library
 
-The first step is to define how your library can be loaded from the test framework. This will let your library to be reused by other library test.
+The first step is to define how your library can be loaded from the test framework. This will let your library to be reused by other library tests.
 
 1. Create a new file `./src/testing/index.ts` with the following content
 

docs/extending-typespec/create-decorators.md

@@ -25,7 +25,7 @@ extern dec logType(target: unknown, name: string);
 
 ## Decorator target
 
-The first parameter of the decorator represents the typespec type(s) that the decorator can be applied on.
+The first parameter of the decorator represents the TypeSpec type(s) that the decorator can be applied on.
 
 You can specify multiple potential target type using an `union expression`
 
@@ -43,7 +43,7 @@ A decorator parameter can be marked optional using `?`
 extern dec track(target: Model | Enum, name?: valueof string);
 ```
 
-### Rest parameters
+### REST parameters
 
 A decorator's last parameter can be prefixed with `...` to collect all the remaining arguments. The type of that parameter must be an `array expression`
 
@@ -114,7 +114,7 @@ model Dog {
 
 ### Decorator parameter marshalling
 
-For certain TypeSpec types(Literal types) the decorator do not receive the actual type but a marshalled value if the decorator parmaeter type is a `valueof`. This is to simplify the most common cases.
+For certain TypeSpec types (Literal types) the decorator do not receive the actual type but a marshalled value if the decorator parmaeter type is a `valueof`. This is to simplify the most common cases.
 
 | TypeSpec Type     | Marshalled value in JS |
 | ----------------- | ---------------------- |
@@ -209,11 +209,11 @@ import type { reportDiagnostic } from "./lib.js";
 export function $customName(context: DecoratorContext, target: Type, name: string) {
   reportDiagnostic({
     code: "custom-name-invalid",
-    target: context.decoratorTarget, // Get location of @customName decorator in typespec document.
+    target: context.decoratorTarget, // Get location of @customName decorator in TypeSpec document.
   });
   reportDiagnostic({
     code: "bad-name",
-    target: context.getArgumentTarget(0), // Get location of {name} argument in typespec document.
+    target: context.getArgumentTarget(0), // Get location of {name} argument in TypeSpec document.
   });
 }
 ```

docs/extending-typespec/diagnostics.md

@@ -2,14 +2,14 @@
 title: Diagnostics
 ---
 
-TypeSpec compiler report errors and warnings in the spec using the diagnostic API.
+The TypeSpec compiler reports errors and warnings in the spec using the diagnostic API.
 
 ## Best practices
 
 - ❌ Do not use `throw` to report errors. Any exception thrown like this will be presented as a bug in your library to the user.
 - ✅ Use diagnostic API to report expected errors and warnings.
   - ✅ Use `reportDiagnostic` in a decorator, `$onValidate` or `$onEmit`
-  - ❌ Do not use `reportDiagnostic` in an accessor(A function meant to be consumed in another library or emitter). See [collect diagnostics section](#collect-diagnostics)
+  - ❌ Do not use `reportDiagnostic` in an accessor (A function meant to be consumed in another library or emitter). See [collect diagnostics section](#collect-diagnostics)
 
 ## Diagnostic specification
 

docs/extending-typespec/emitter-framework.md

@@ -30,7 +30,7 @@ To create your asset emitter, call `getAssetEmitter` on your emit context in `$o
 export async function $onEmit(context: EmitContext) {
   const assetEmitter = context.getAssetEmitter(MyTypeEmitter);
 
-  // emit my entire typespec program
+  // emit my entire TypeSpec program
   assetEmitter.emitProgram();
   // or, maybe emit types just in a specific namespace
   const ns = context.program.resolveTypeReference("MyNamespace")!;
@@ -93,7 +93,7 @@ class MyCodeEmitter extends CodeTypeEmitter {
 }
 ```
 
-If we have a typespec program that looks like:
+If we have a TypeSpec program that looks like:
 
 ```typespec
 model Pet {}
@@ -148,7 +148,7 @@ class MyCodeEmitter extends CodeTypeEmitter {
 }
 ```
 
-Now given a typespec program like:
+Now given a TypeSpec program like:
 
 ```typespec
 model Pet {

docs/extending-typespec/emitters-basics.md

@@ -5,7 +5,7 @@ title: Emitters
 
 # Writing emitters
 
-TypeSpec emitters are libraries that use various TypeSpec compiler APIs to reflect on the typespec compilation and produce generated artifacts. The typespec standard library includes an emitter for OpenAPI version 3.0, but odds are good you will want to emit TypeSpec to another output format. In fact, one of TypeSpec's main benefits is how easy it is to use TypeSpec as a source of truth for all data shapes, and the ease of writing an emitter is a big part of that story.
+TypeSpec emitters are libraries that use various TypeSpec compiler APIs to reflect on the TypeSpec compilation and produce generated artifacts. The TypeSpec standard library includes an emitter for OpenAPI version 3.0, but odds are good you will want to emit TypeSpec to another output format. In fact, one of TypeSpec's main benefits is how easy it is to use TypeSpec as a source of truth for all data shapes, and the ease of writing an emitter is a big part of that story.
 
 ## Getting started
 
@@ -17,7 +17,7 @@ Setup the boilerplate for an emitter using our template:
 tsp init --template emitter-ts
 ```
 
-or follow [these steps](./basics.md) to initialize a typespec library.
+or follow [these steps](./basics.md) to initialize a TypeSpec library.
 
 ## $onEmit
 
@@ -106,7 +106,7 @@ export async function $onEmit(context: EmitContext<EmitterOptions>) {
 Specify that the value for this option should resolve to an absolute path. e.g. `"{project-root}/dir"`.
 
 :::important
-It is recommended that all options that involve path use this. Using relative path can be confusing for users on as it is not clear what the relative path is relative to. And more importantly relative path if not careful are resolved relative to the `cwd` in node file system which result in spec only compiling from the the project root.
+It is recommended that all options that involve path use this. Using relative path can be confusing for users on as it is not clear what the relative path is relative to. And more importantly relative path if not careful are resolved relative to the `cwd` in Node file system which result in spec only compiling from the the project root.
 :::
 
 Example:
@@ -152,7 +152,7 @@ navigateProgram(program, {
 
 You can provide a callback for every kind of TypeSpec type. The walker will call your callback pre-order, i.e. as soon as it sees a type for the first time it will invoke your callback. You can invoke callback post-order instead by prefixing the type name with `exit`, for example `exitModel(m)`.
 
-Note that the semantic walker will visit all types in the program including built-in TypeSpec types and typespec types defined by any libraries you're using. Care must be taken to filter out any types you do not intend to emit. Sometimes this is quite difficult, so a custom traversal may be easier.
+Note that the semantic walker will visit all types in the program including built-in TypeSpec types and TypeSpec types defined by any libraries you're using. Care must be taken to filter out any types you do not intend to emit. Sometimes this is quite difficult, so a custom traversal may be easier.
 
 ### Custom traversal
 
@@ -190,7 +190,7 @@ function emitModel(model: Model) {
 }
 ```
 
-### Resolving a typespec type
+### Resolving a TypeSpec type
 
 Sometimes you might want to get access to a known TypeSpec type in the type graph, for example a model that you have defined in your library.
 
@@ -200,12 +200,12 @@ A helper is provided on the program to do that.
 program.resolveTypeReference(reference: string): Type | undefined;
 ```
 
-The reference must be a valid typespec reference(Like you would have it in a typespec document)
+The reference must be a valid TypeSpec reference (like you would have it in a TypeSpec document)
 
 **Example**
 
 ```ts
-program.resolveTypeReference("TypeSpec.string"); // Resolve typespec string intrinsic type
+program.resolveTypeReference("TypeSpec.string"); // Resolve TypeSpec string intrinsic type
 program.resolveTypeReference("MyOrg.MyLibrary.MyEnum"); // Resolve `MyEnum` defined in `MyOrg.MyLibrary` namespace.
 ```
 
@@ -218,9 +218,9 @@ program.resolveTypeReference("model Foo {}"); // Resolve `[undefined, diagnostic
 
 ## Emitting files to disk
 
-Since an emitter is a node library, you could use standard `fs` APIs to write files. However, this approach has a drawback - your emitter will not work in the browser, and will not work with the test framework that depends on storing emitted files in an in-memory file system.
+Since an emitter is a Node library, you could use standard `fs` APIs to write files. However, this approach has a drawback - your emitter will not work in the browser, and will not work with the test framework that depends on storing emitted files in an in-memory file system.
 
-Instead, use the compiler [`host` interface](#todo) to access the file system. The API is equivalent to the node API but works in a wider range of scenarios.
+Instead, use the compiler [`host` interface](#todo) to access the file system. The API is equivalent to the Node API but works in a wider range of scenarios.
 
 In order to know where to emit files, the emitter context has a `emitterOutputDir` property that is automatically resolved using the `emitter-output-dir` built-in emitter options. This is set to `{cwd}/tsp-output/{emitter-name}` by default, but can be overridden by the user. Do not use the `compilerOptions.outputDir`
 
@@ -230,7 +230,7 @@ Scalars are types in TypeSpec that most likely have a primitive or built-in data
 
 Recommended logic for emitting scalar is to:
 
-1. If scalar is a known scalar(e.g. `int32`), emit the known mapping.
+1. If scalar is a known scalar (e.g. `int32`), emit the known mapping.
 2. Otherwise check scalar `baseScalar` and go back to `1.`
    2.1 After resolving which scalar apply any decorators
 

docs/extending-typespec/linters.md

@@ -7,9 +7,9 @@ title: Linters
 
 ## Linter vs `onValidate`
 
-TypeSpec library can probide a `$onValidate` hook which can be used to validate the typespec program is valid in the eye of your library.
+TypeSpec library can probide a `$onValidate` hook which can be used to validate the TypeSpec program is valid in the eye of your library.
 
-A linter on the other hand might be a validation that is optional, the program is correct but there could be some improvements. For example requiring documentation on every type. This is not something that is needed to represent the typespec program but without it the end user experience might suffer.
+A linter on the other hand might be a validation that is optional, the program is correct but there could be some improvements. For example requiring documentation on every type. This is not something that is needed to represent the TypeSpec program but without it the end user experience might suffer.
 Linters need to be explicitly enabled. `$onValidate` will be run automatically if that library is imported.
 
 ## Writing a linter