Skip to content

Commit a03790f

Browse files
fix: Restore accidentally lost heading hierarchies (microsoft#2880)
1 parent e28ae73 commit a03790f

18 files changed

Lines changed: 162 additions & 162 deletions

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ oneline: "Recommendations for writing d.ts files"
77

88
## General Types
99

10-
## `Number`, `String`, `Boolean`, `Symbol` and `Object`
10+
### `Number`, `String`, `Boolean`, `Symbol` and `Object`
1111

1212
**Don't** ever use the types `Number`, `String`, `Boolean`, `Symbol`, or `Object`
1313
These types refer to non-primitive boxed objects that are almost never used appropriately in JavaScript code.
@@ -26,12 +26,12 @@ function reverse(s: string): string;
2626

2727
Instead of `Object`, use the non-primitive `object` type ([added in TypeScript 2.2](../release-notes/typescript-2-2.html#object-type)).
2828

29-
## Generics
29+
### Generics
3030

3131
**Don't** ever have a generic type which doesn't use its type parameter.
3232
See more details in [TypeScript FAQ page](https://github.com/Microsoft/TypeScript/wiki/FAQ#why-doesnt-type-inference-work-on-this-interface-interface-foot--).
3333

34-
## any
34+
### any
3535

3636
**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.
3737

@@ -41,7 +41,7 @@ In cases where you don't know what type you want to accept, or when you want to
4141

4242
## Callback Types
4343

44-
## Return Types of Callbacks
44+
### Return Types of Callbacks
4545

4646
<!-- TODO: Reword; these examples make no sense in the context of a declaration file -->
4747

@@ -72,7 +72,7 @@ function fn(x: () => void) {
7272
}
7373
```
7474

75-
## Optional Parameters in Callbacks
75+
### Optional Parameters in Callbacks
7676

7777
**Don't** use optional parameters in callbacks unless you really mean it:
7878

@@ -97,7 +97,7 @@ interface Fetcher {
9797
}
9898
```
9999

100-
## Overloads and Callbacks
100+
### Overloads and Callbacks
101101

102102
**Don't** write separate overloads that differ only on callback arity:
103103

@@ -125,7 +125,7 @@ Providing a shorter callback first allows incorrectly-typed functions to be pass
125125

126126
## Function Overloads
127127

128-
## Ordering
128+
### Ordering
129129

130130
**Don't** put more general overloads before more specific overloads:
131131

@@ -154,7 +154,7 @@ var x = fn(myElem); // x: string, :)
154154
**Why:** TypeScript chooses the _first matching overload_ when resolving function calls.
155155
When an earlier overload is "more general" than a later one, the later one is effectively hidden and cannot be called.
156156

157-
## Use Optional Parameters
157+
### Use Optional Parameters
158158

159159
**Don't** write several overloads that differ only in trailing parameters:
160160

@@ -203,7 +203,7 @@ var x: Example;
203203
x.diff("something", true ? undefined : "hour");
204204
```
205205

206-
## Use Union Types
206+
### Use Union Types
207207

208208
**Don't** write overloads that differ by type in only one argument position:
209209

packages/documentation/copy/en/declaration-files/Library Structures.md

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ We'll give hints on how to identify structure both based on its _usage_ and its
2222
Depending on the library's documentation and organization, one might be easier than the other.
2323
We recommend using whichever is more comfortable to you.
2424

25-
## What should you look for?
25+
### What should you look for?
2626

2727
Question to ask yourself while looking at a library you are trying to type.
2828

@@ -34,9 +34,9 @@ Question to ask yourself while looking at a library you are trying to type.
3434

3535
Does it add a global object? Does it use `require` or `import`/`export` statements?
3636

37-
## Smaller samples for different types of libraries
37+
### Smaller samples for different types of libraries
3838

39-
## Modular Libraries
39+
### Modular Libraries
4040

4141
Almost every modern Node.js library falls into the module family.
4242
These type of libraries only work in a JS environment with a module loader.
@@ -71,7 +71,7 @@ define(..., ['someLib'], function(someLib) {
7171

7272
As with global modules, you might see these examples in the documentation of [a UMD](#umd) module, so be sure to check the code or documentation.
7373

74-
### Identifying a Module Library from Code
74+
#### Identifying a Module Library from Code
7575

7676
Modular libraries will typically have at least some of the following:
7777

@@ -83,7 +83,7 @@ They will rarely have:
8383

8484
- Assignments to properties of `window` or `global`
8585

86-
### Templates For Modules
86+
#### Templates For Modules
8787

8888
There are four templates available for modules,
8989
[`module.d.ts`](/docs/handbook/declaration-files/templates/module-d-ts.html), [`module-class.d.ts`](/docs/handbook/declaration-files/templates/module-class-d-ts.html), [`module-function.d.ts`](/docs/handbook/declaration-files/templates/module-function-d-ts.html) and [`module-plugin.d.ts`](/docs/handbook/declaration-files/templates/module-plugin-d-ts.html).
@@ -113,7 +113,7 @@ const jest = require("jest");
113113
require("jest-matchers-files");
114114
```
115115

116-
## Global Libraries
116+
### Global Libraries
117117

118118
A _global_ library is one that can be accessed from the global scope (i.e. without using any form of `import`).
119119
Many libraries simply expose one or more global variables for use.
@@ -135,7 +135,7 @@ Today, most popular globally-accessible libraries are actually written as UMD li
135135
UMD library documentation is hard to distinguish from global library documentation.
136136
Before writing a global declaration file, make sure the library isn't actually UMD.
137137

138-
### Identifying a Global Library from Code
138+
#### Identifying a Global Library from Code
139139

140140
Global library code is usually extremely simple.
141141
A global "Hello, world" library might look like this:
@@ -178,17 +178,17 @@ You _won't_ see:
178178
- Calls to `define(...)`
179179
- Documentation describing how to `require` or import the library
180180

181-
### Examples of Global Libraries
181+
#### Examples of Global Libraries
182182

183183
Because it's usually easy to turn a global library into a UMD library, very few popular libraries are still written in the global style.
184184
However, libraries that are small and require the DOM (or have _no_ dependencies) may still be global.
185185

186-
### Global Library Template
186+
#### Global Library Template
187187

188188
The template file [`global.d.ts`](/docs/handbook/declaration-files/templates/global-plugin-d-ts.html) defines an example library `myLib`.
189189
Be sure to read the ["Preventing Name Conflicts" footnote](#preventing-name-conflicts).
190190

191-
## _UMD_
191+
### _UMD_
192192

193193
A _UMD_ module is one that can _either_ be used as module (through an import), or as a global (when run in an environment without a module loader).
194194
Many popular libraries, such as [Moment.js](https://momentjs.com/), are written this way.
@@ -205,7 +205,7 @@ whereas in a vanilla browser environment you would write:
205205
console.log(moment.format());
206206
```
207207

208-
### Identifying a UMD library
208+
#### Identifying a UMD library
209209

210210
[UMD modules](https://github.com/umdjs/umd) check for the existence of a module loader environment.
211211
This is an easy-to-spot pattern that looks something like this:
@@ -227,12 +227,12 @@ If you see tests for `typeof define`, `typeof window`, or `typeof module` in the
227227
Documentation for UMD libraries will also often demonstrate a "Using in Node.js" example showing `require`,
228228
and a "Using in the browser" example showing using a `<script>` tag to load the script.
229229
230-
### Examples of UMD libraries
230+
#### Examples of UMD libraries
231231
232232
Most popular libraries are now available as UMD packages.
233233
Examples include [jQuery](https://jquery.com/), [Moment.js](https://momentjs.com/), [lodash](https://lodash.com/), and many more.
234234
235-
### Template
235+
#### Template
236236
237237
Use the [`module-plugin.d.ts`](/docs/handbook/declaration-files/templates/module-plugin-d-ts.html) template.
238238
@@ -241,7 +241,7 @@ Use the [`module-plugin.d.ts`](/docs/handbook/declaration-files/templates/module
241241
There are several kinds of dependencies your library might have.
242242
This section shows how to import them into the declaration file.
243243
244-
## Dependencies on Global Libraries
244+
### Dependencies on Global Libraries
245245
246246
If your library depends on a global library, use a `/// <reference types="..." />` directive:
247247

@@ -251,7 +251,7 @@ If your library depends on a global library, use a `/// <reference types="..." /
251251
function getThing(): someLib.thing;
252252
```
253253

254-
## Dependencies on Modules
254+
### Dependencies on Modules
255255

256256
If your library depends on a module, use an `import` statement:
257257

@@ -261,9 +261,9 @@ import * as moment from "moment";
261261
function getThing(): moment;
262262
```
263263

264-
## Dependencies on UMD libraries
264+
### Dependencies on UMD libraries
265265

266-
### From a Global Library
266+
#### From a Global Library
267267

268268
If your global library depends on a UMD module, use a `/// <reference types` directive:
269269

@@ -273,7 +273,7 @@ If your global library depends on a UMD module, use a `/// <reference types` dir
273273
function getThing(): moment;
274274
```
275275

276-
### From a Module or UMD Library
276+
#### From a Module or UMD Library
277277

278278
If your module or UMD library depends on a UMD library, use an `import` statement:
279279

@@ -285,7 +285,7 @@ Do _not_ use a `/// <reference` directive to declare a dependency to a UMD libra
285285

286286
## Footnotes
287287

288-
## Preventing Name Conflicts
288+
### Preventing Name Conflicts
289289

290290
Note that it's possible to define many types in the global scope when writing a global declaration file.
291291
We strongly discourage this as it leads to possible unresolvable name conflicts when many declaration files are in a project.
@@ -308,7 +308,7 @@ interface CatsKittySettings {}
308308
309309
This guidance also ensures that the library can be transitioned to UMD without breaking declaration file users.
310310
311-
## The Impact of ES6 on Module Call Signatures
311+
### The Impact of ES6 on Module Call Signatures
312312
313313
Many popular libraries, such as Express, expose themselves as a callable function when imported.
314314
For example, the typical Express usage looks like this:

packages/documentation/copy/en/declaration-files/templates/global-plugin.d.ts.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@ Use the [`global-modifying-module.d.ts`](/docs/handbook/declaration-files/templa
151151
There are several kinds of dependencies your library might have.
152152
This section shows how to import them into the declaration file.
153153

154-
## Dependencies on Global Libraries
154+
### Dependencies on Global Libraries
155155

156156
If your library depends on a global library, use a `/// <reference types="..." />` directive:
157157

@@ -161,7 +161,7 @@ If your library depends on a global library, use a `/// <reference types="..." /
161161
function getThing(): someLib.thing;
162162
```
163163

164-
## Dependencies on Modules
164+
### Dependencies on Modules
165165

166166
If your library depends on a module, use an `import` statement:
167167

@@ -171,9 +171,9 @@ import * as moment from "moment";
171171
function getThing(): moment;
172172
```
173173

174-
## Dependencies on UMD libraries
174+
### Dependencies on UMD libraries
175175

176-
### From a Global Library
176+
#### From a Global Library
177177

178178
If your global library depends on a UMD module, use a `/// <reference types` directive:
179179

@@ -183,7 +183,7 @@ If your global library depends on a UMD module, use a `/// <reference types` dir
183183
function getThing(): moment;
184184
```
185185

186-
### From a Module or UMD Library
186+
#### From a Module or UMD Library
187187

188188
If your module or UMD library depends on a UMD library, use an `import` statement:
189189

@@ -195,7 +195,7 @@ Do _not_ use a `/// <reference` directive to declare a dependency to a UMD libra
195195

196196
## Footnotes
197197

198-
## Preventing Name Conflicts
198+
### Preventing Name Conflicts
199199

200200
Note that it's possible to define many types in the global scope when writing a global declaration file.
201201
We strongly discourage this as it leads to possible unresolvable name conflicts when many declaration files are in a project.
@@ -218,13 +218,13 @@ interface CatsKittySettings {}
218218
219219
This guidance also ensures that the library can be transitioned to UMD without breaking declaration file users.
220220
221-
## The Impact of ES6 on Module Plugins
221+
### The Impact of ES6 on Module Plugins
222222
223223
Some plugins add or modify top-level exports on existing modules.
224224
While this is legal in CommonJS and other loaders, ES6 modules are considered immutable and this pattern will not be possible.
225225
Because TypeScript is loader-agnostic, there is no compile-time enforcement of this policy, but developers intending to transition to an ES6 module loader should be aware of this.
226226
227-
## The Impact of ES6 on Module Call Signatures
227+
### The Impact of ES6 on Module Call Signatures
228228
229229
Many popular libraries, such as Express, expose themselves as a callable function when imported.
230230
For example, the typical Express usage looks like this:
@@ -239,7 +239,7 @@ the top-level module object is _never_ callable.
239239
The most common solution here is to define a `default` export for a callable/constructable object;
240240
some module loader shims will automatically detect this situation and replace the top-level object with the `default` export.
241241
242-
## Library file layout
242+
### Library file layout
243243
244244
The layout of your declaration files should mirror the layout of the library.
245245

0 commit comments

Comments
 (0)