Merge pull request #543 from microsoft/new-dts

Start on updating the templates for modules

.vscode/extensions.json

@@ -4,4 +4,4 @@
     "streetsidesoftware.code-spell-checker-portuguese-brazilian",
     "streetsidesoftware.code-spell-checker-spanish"
   ]
-}
+}

docs/Converting Twoslash Code Samples.md

@@ -1,5 +1,7 @@
 ### A Guide to Converting to Twoslash
 
+To run the site with Twoslash enabled you need to use `yarn start-twoslash`.
+
 Code samples on the TypeScript Website should run through [Twoslash](https://github.com/microsoft/TypeScript-Website/tree/v2/packages/ts-twoslasher#typescript-twoslash) which lets the compiler do more of the work.
 
 Without twoslash a code sample looks like:

packages/documentation/copy/en/Basic Types.md

@@ -10,15 +10,15 @@ oneline: "Step one in learning TypeScript: The basics types."
 For programs to be useful, we need to be able to work with some of the simplest units of data: numbers, strings, structures, boolean values, and the like.
 In TypeScript, we support much the same types as you would expect in JavaScript, with a convenient enumeration type thrown in to help things along.
 
-# Boolean
+## Boolean
 
 The most basic datatype is the simple true/false value, which JavaScript and TypeScript call a `boolean` value.
 
 ```ts  twoslash
 let isDone: boolean = false;
 ```
 
-# Number
+##   Number
 
 As in JavaScript, all numbers in TypeScript are either floating point values or BigIntegers.
 These floating point numbers get the type `number`, while BigIntegers get the type `bigint`.
@@ -33,7 +33,7 @@ let octal: number = 0o744;
 let big: bigint = 100n;
 ```
 
-# String
+## String
 
 Another fundamental part of creating programs in JavaScript for webpages and servers alike is working with textual data.
 As in other languages, we use the type `string` to refer to these textual datatypes.
@@ -70,7 +70,7 @@ let sentence: string =
   " years old next month.";
 ```
 
-# Array
+## Array
 
 TypeScript, like JavaScript, allows you to work with arrays of values.
 Array types can be written in one of two ways.
@@ -125,7 +125,7 @@ x[3] = "world";
 console.log(x[5].toString());
 ```
 
-# Enum
+## Enum
 
 A helpful addition to the standard set of datatypes from JavaScript is the `enum`.
 As in languages like C#, an enum is a way of giving more friendly names to sets of numeric values.
@@ -215,7 +215,7 @@ if (typeof maybe === "string") {
 }
 ```
 
-# Any
+## Any
 
 In some situations, not all type information is available or it's declaration would take an inappropriate amount of effort.
 These may occur for values from code that has been written without TypeScript or a 3rd party library.
@@ -256,7 +256,7 @@ let d = looselyTyped.a.b.c.d;
 After all, remember that all the convenience of `any` comes at the cost of losing type safety.
 Type safety is one of the main motivations for using TypeScript and you should try to avoid using `any` when not necessary.
 
-# Void
+## Void
 
 `void` is a little like the opposite of `any`: the absence of having any type at all.
 You may commonly see this as the return type of functions that do not return a value:
@@ -298,7 +298,7 @@ Union types are an advanced topic that we'll cover in a later chapter.
 
 > As a note: we encourage the use of `--strictNullChecks` when possible, but for the purposes of this handbook, we will assume it is turned off.
 
-# Never
+## Never
 
 The `never` type represents the type of values that never occur.
 For instance, `never` is the return type for a function expression or an arrow function expression that always throws an exception or one that never returns.
@@ -348,7 +348,7 @@ create(undefined);
 
 Generally, you won't need to use this.
 
-# Type assertions
+## Type assertions
 
 Sometimes you'll end up in a situation where you'll know more about a value than TypeScript does.
 Usually this will happen when you know the type of some entity could be more specific than its current type.
@@ -384,3 +384,30 @@ Using one over the other is mostly a choice of preference; however, when using T
 You may have noticed that so far, we've been using the `let` keyword instead of JavaScript's `var` keyword which you might be more familiar with.
 The `let` keyword is actually a newer JavaScript construct that TypeScript makes available.
 We'll discuss the details later, but many common problems in JavaScript are alleviated by using `let`, so you should use it instead of `var` whenever possible.
+
+
+## About `Number`, `String`, `Boolean`, `Symbol` and `Object`
+
+It can be tempting to think that the types `Number`, `String`, `Boolean`, `Symbol`, or `Object` are the same as the lowercase versions.
+These types do not refer to the language primitives, and almost never should be used as a type.
+
+```ts twoslash
+// @errors: 2339
+function reverse(s: String): String { 
+  return s.split("").reverse().join("")
+}
+
+reverse("hello world")
+```
+
+Instead, use the types `number`, `string`, `boolean`, and `symbol`.
+
+```ts twoslash
+function reverse(s: string): string { 
+  return s.split("").reverse().join("") 
+}
+
+reverse("hello world")
+```
+
+Instead of `Object`, use the non-primitive `object` type

packages/documentation/copy/en/declaration files/By Example.md

@@ -1,63 +1,16 @@
 ---
-title: By Example
+title: Declaration Reference
 layout: docs
 permalink: /docs/handbook/declaration-files/by-example.html
 oneline: "How to create a d.ts file for a module"
 ---
 
-# Introduction
-
 The purpose of this guide is to teach you how to write a high-quality definition file.
 This guide is structured by showing documentation for some API, along with sample usage of that API,
 and explaining how to write the corresponding declaration.
 
 These examples are ordered in approximately increasing order of complexity.
 
-# The Examples
-
-## Global Variables
-
-_Documentation_
-
-> The global variable `foo` contains the number of widgets present.
-
-_Code_
-
-```ts
-console.log("Half the number of widgets is " + foo / 2);
-```
-
-_Declaration_
-
-Use `declare var` to declare variables.
-If the variable is read-only, you can use `declare const`.
-You can also use `declare let` if the variable is block-scoped.
-
-```ts
-/** The number of widgets present */
-declare var foo: number;
-```
-
-## Global Functions
-
-_Documentation_
-
-> You can call the function `greet` with a string to show a greeting to the user.
-
-_Code_
-
-```ts
-greet("hello, world");
-```
-
-_Declaration_
-
-Use `declare function` to declare functions.
-
-```ts
-declare function greet(greeting: string): void;
-```
-
 ## Objects with Properties
 
 _Documentation_
@@ -253,23 +206,46 @@ declare class Greeter {
 }
 ```
 
-<!-- Template
+## Global Variables
 
-##
+_Documentation_
 
-*Documentation*
->
+> The global variable `foo` contains the number of widgets present.
 
-*Code*
+_Code_
 
 ```ts
+console.log("Half the number of widgets is " + foo / 2);
+```
+
+_Declaration_
+
+Use `declare var` to declare variables.
+If the variable is read-only, you can use `declare const`.
+You can also use `declare let` if the variable is block-scoped.
 
+```ts
+/** The number of widgets present */
+declare var foo: number;
 ```
 
-*Declaration*
+## Global Functions
+
+_Documentation_
+
+> You can call the function `greet` with a string to show a greeting to the user.
+
+_Code_
 
 ```ts
+greet("hello, world");
+```
+
+_Declaration_
 
+Use `declare function` to declare functions.
+
+```ts
+declare function greet(greeting: string): void;
 ```
 
--->

packages/documentation/copy/en/declaration files/Deep Dive.md

@@ -5,19 +5,19 @@ permalink: /docs/handbook/declaration-files/deep-dive.html
 oneline: "How do d.ts files work, a deep dive"
 ---
 
-# Definition File Theory: A Deep Dive
+## Declaration File Theory: A Deep Dive
 
 Structuring modules to give the exact API shape you want can be tricky.
 For example, we might want a module that can be invoked with or without `new` to produce different types,
 has a variety of named types exposed in a hierarchy,
 and has some properties on the module object as well.
 
-By reading this guide, you'll have the tools to write complex definition files that expose a friendly API surface.
+By reading this guide, you'll have the tools to write complex declaration files that expose a friendly API surface.
 This guide focuses on module (or UMD) libraries because the options here are more varied.
 
 ## Key Concepts
 
-You can fully understand how to make any shape of definition
+You can fully understand how to make any shape of declaration
 by understanding some key concepts of how TypeScript works.
 
 ### Types
@@ -229,8 +229,4 @@ The second block creates the following name meanings:
 - A value `C` that is a property of the `X.Z` value
 - A type `X`
 
-## Using with `export =` or `import`
-
-An important rule is that `export` and `import` declarations export or import _all meanings_ of their targets.
-
 <!-- TODO: Write more on that. -->

packages/documentation/copy/en/declaration files/Do's and Don'ts.md

@@ -35,7 +35,7 @@ See more details in [TypeScript FAQ page](https://github.com/Microsoft/TypeScrip
 
 _Don't_ use `any` as a type unless you are in the process of migrating a JavaScript project to TypeScript.  The compiler _effectively_ treats `any` as "please turn off type checking for this thing".  It is similar to putting an `@ts-ignore` comment around every usage of the variable.  This can be very helpful when you are first migrating a JavaScript project to TypeScript as you can set the type for stuff you haven't migrated yet as `any`, but in a full TypeScript project you are disabling type checking for any parts of your program that use it.
 
-In cases where you don't know what type you want to accept, or when you want to accept anything because you will be blindly passing it through without interacting with it, you can use [`unknown`](/play/index.html?e=136#example/unknown-and-never).
+In cases where you don't know what type you want to accept, or when you want to accept anything because you will be blindly passing it through without interacting with it, you can use [`unknown`](/play/#example/unknown-and-never).
 
 <!-- TODO: More -->
 

packages/documentation/copy/en/declaration files/Introduction.md

@@ -2,30 +2,33 @@
 title: Introduction
 layout: docs
 permalink: /docs/handbook/declaration-files/introduction.html
-oneline: "How to write a high-quality TypeScript Ddeclaration (d.ts) file"
+oneline: "How to write a high-quality TypeScript Declaration (d.ts) file"
 ---
 
-This guide is designed to teach you how to write a high-quality TypeScript Declaration File.
+This guide is designed to teach you how to write a high-quality TypeScript Declaration File. We need to assume basic familiarity with the TypeScript language in order to get started.
 
-We assume basic familiarity with the TypeScript language.
 If you haven't already, you should read the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/basic-types.html)
-to familiarize yourself with basic concepts, especially types and namespaces.
+to familiarize yourself with basic concepts, especially types and modules.
 
-# Sections
+The most common case for learning how .d.ts files work is that you're typing an npm package with no types. 
+In that case, you can jump straight to [Modules .d.ts](/docs/handbook/declaration-files/templates/module-d-ts.html).
 
-The guide is broken down into the following sections.
+The Declaration Files guide is broken down into the following sections.
+
+## Declaration Reference
+
+We are often faced with writing a declaration file when we only have examples of the underlying library to guide us.
+The [Declaration Reference](/docs/handbook/declaration-files/by-example.html) section shows many common API patterns and how to write declarations for each of them.
+This guide is aimed at the TypeScript novice who may not yet be familiar with every language construct in TypeScript.
 
 ## Library Structures
 
 The [Library Structures](/docs/handbook/declaration-files/library-structures.html) guide helps you understand common library formats and how to write a proper declaration file for each format.
 If you're editing an existing file, you probably don't need to read this section.
-Authors of new declaration files are strongly encouraged to read this section to properly understand how the format of the library influences the writing of the declaration file.
+Authors of new declaration files are strongly encouraged to read this section to properly understand how the format of the library influences the writing of the declaration file. 
 
-## By Example
-
-We are often faced with writing a declaration file when we only have examples of the underlying library to guide us.
-The [By Example](/docs/handbook/declaration-files/by-example.html) section shows many common API patterns and how to write declarations for each of them.
-This guide is aimed at the TypeScript novice who may not yet be familiar with every language construct in TypeScript.
+In the Template section you'll find a number of declaration files that serve as a useful starting point
+when writing a new file. If you already know what your structure is, see the d.ts Template section in the sidebar.
 
 ## "Do"s and "Don't"s
 
@@ -41,12 +44,6 @@ For seasoned authors interested in the underlying mechanics of how declaration f
 the [Deep Dive](/docs/handbook/declaration-files/deep-dive.html) section explains many advanced concepts in declaration writing,
 and shows how to leverage these concepts to create cleaner and more intuitive declaration files.
 
-## Templates
-
-In [Templates](/docs/handbook/declaration-files/templates.html) you'll find a number of declaration files that serve as a useful starting point
-when writing a new file.
-Refer to the documentation in [Library Structures](/docs/handbook/declaration-files/library-structures.html) to figure out which template file to use.
-
 ## Publish to npm
 
 The [Publishing](/docs/handbook/declaration-files/publishing.html) section explains how to publish your declaration files to an npm package, and shows how to manage your dependent packages.