Skip to content

Commit a56d576

Browse files
alesgenovaalesgenova
authored
Merge pull request #49 from alesgenova/tsdoc
Add TSDoc info to all public classes and interfaces
2 parents c1aaa33 + 2143d73 commit a56d576

18 files changed

+1071
-59
lines changed

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
node_modules/
22
dist/
33
www/
4+
docs/
5+
temp/
46

57
coverage/
68
.rpt2_cache/

‎.prettierignore

+3
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,7 @@
33
/www
44
/coverage
55
/scripts
6+
/api
7+
/docs
8+
/temp
69
*.config.js

‎README.md

+8-1
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,8 @@ In this [live demo](https://alesgenova.github.io/post-me-demo) the main window c
3333
5. [Callbacks as parameters](#callbacks)
3434
6. [Transfer vs Clone](#transfer)
3535
7. [Debugging](#debugging)
36-
8. [References](#references)
36+
8. [API Documentation](#api)
37+
9. [References](#references)
3738

3839
<a id="install"></a>
3940

@@ -386,6 +387,12 @@ ParentHandshake(messenger).then((connection) => {
386387
Output:
387388
![debug output](debug.png)
388389
390+
<a id="api"></a>
391+
392+
## API Documentation
393+
394+
The full [__API reference__](https://alesgenova.github.io/post-me/post-me.html) cab be found [here](https://alesgenova.github.io/post-me/post-me.html).
395+
389396
<a id="references"></a>
390397
391398
## References

‎api-extractor.json

+339
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,339 @@
1+
/**
2+
* Config file for API Extractor. For more info, please visit: https://api-extractor.com
3+
*/
4+
{
5+
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
6+
/**
7+
* Optionally specifies another JSON config file that this file extends from. This provides a way for
8+
* standard settings to be shared across multiple projects.
9+
*
10+
* If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
11+
* the "extends" field. Otherwise, the first path segment is interpreted as an NPM package name, and will be
12+
* resolved using NodeJS require().
13+
*
14+
* SUPPORTED TOKENS: none
15+
* DEFAULT VALUE: ""
16+
*/
17+
// "extends": "./shared/api-extractor-base.json"
18+
// "extends": "my-package/include/api-extractor-base.json"
19+
/**
20+
* Determines the "<projectFolder>" token that can be used with other config file settings. The project folder
21+
* typically contains the tsconfig.json and package.json config files, but the path is user-defined.
22+
*
23+
* The path is resolved relative to the folder of the config file that contains the setting.
24+
*
25+
* The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
26+
* parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
27+
* that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error
28+
* will be reported.
29+
*
30+
* SUPPORTED TOKENS: <lookup>
31+
* DEFAULT VALUE: "<lookup>"
32+
*/
33+
// "projectFolder": "..",
34+
/**
35+
* (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis. API Extractor
36+
* analyzes the symbols exported by this module.
37+
*
38+
* The file extension must be ".d.ts" and not ".ts".
39+
*
40+
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
41+
* prepend a folder token such as "<projectFolder>".
42+
*
43+
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
44+
*/
45+
"mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
46+
/**
47+
* A list of NPM package names whose exports should be treated as part of this package.
48+
*
49+
* For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
50+
* and another NPM package "library2" is embedded in this bundle. Some types from library2 may become part
51+
* of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
52+
* imports library2. To avoid this, we can specify:
53+
*
54+
* "bundledPackages": [ "library2" ],
55+
*
56+
* This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
57+
* local files for library1.
58+
*/
59+
"bundledPackages": [],
60+
/**
61+
* Determines how the TypeScript compiler engine will be invoked by API Extractor.
62+
*/
63+
"compiler": {
64+
/**
65+
* Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
66+
*
67+
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
68+
* prepend a folder token such as "<projectFolder>".
69+
*
70+
* Note: This setting will be ignored if "overrideTsconfig" is used.
71+
*
72+
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
73+
* DEFAULT VALUE: "<projectFolder>/tsconfig.json"
74+
*/
75+
// "tsconfigFilePath": "<projectFolder>/tsconfig.json",
76+
/**
77+
* Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
78+
* The object must conform to the TypeScript tsconfig schema:
79+
*
80+
* http://json.schemastore.org/tsconfig
81+
*
82+
* If omitted, then the tsconfig.json file will be read from the "projectFolder".
83+
*
84+
* DEFAULT VALUE: no overrideTsconfig section
85+
*/
86+
// "overrideTsconfig": {
87+
// . . .
88+
// }
89+
/**
90+
* This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
91+
* and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
92+
* dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
93+
* for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
94+
*
95+
* DEFAULT VALUE: false
96+
*/
97+
// "skipLibCheck": true,
98+
},
99+
/**
100+
* Configures how the API report file (*.api.md) will be generated.
101+
*/
102+
"apiReport": {
103+
/**
104+
* (REQUIRED) Whether to generate an API report.
105+
*/
106+
"enabled": true,
107+
/**
108+
* The filename for the API report files. It will be combined with "reportFolder" or "reportTempFolder" to produce
109+
* a full file path.
110+
*
111+
* The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
112+
*
113+
* SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
114+
* DEFAULT VALUE: "<unscopedPackageName>.api.md"
115+
*/
116+
// "reportFileName": "<unscopedPackageName>.api.md",
117+
/**
118+
* Specifies the folder where the API report file is written. The file name portion is determined by
119+
* the "reportFileName" setting.
120+
*
121+
* The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy,
122+
* e.g. for an API review.
123+
*
124+
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
125+
* prepend a folder token such as "<projectFolder>".
126+
*
127+
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
128+
* DEFAULT VALUE: "<projectFolder>/etc/"
129+
*/
130+
"reportFolder": "<projectFolder>/api/"
131+
/**
132+
* Specifies the folder where the temporary report file is written. The file name portion is determined by
133+
* the "reportFileName" setting.
134+
*
135+
* After the temporary file is written to disk, it is compared with the file in the "reportFolder".
136+
* If they are different, a production build will fail.
137+
*
138+
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
139+
* prepend a folder token such as "<projectFolder>".
140+
*
141+
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
142+
* DEFAULT VALUE: "<projectFolder>/temp/"
143+
*/
144+
// "reportTempFolder": "<projectFolder>/temp/"
145+
},
146+
/**
147+
* Configures how the doc model file (*.api.json) will be generated.
148+
*/
149+
"docModel": {
150+
/**
151+
* (REQUIRED) Whether to generate a doc model file.
152+
*/
153+
"enabled": true,
154+
/**
155+
* The output path for the doc model file. The file extension should be ".api.json".
156+
*
157+
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
158+
* prepend a folder token such as "<projectFolder>".
159+
*
160+
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
161+
* DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
162+
*/
163+
"apiJsonFilePath": "<projectFolder>/docs/input/<unscopedPackageName>.api.json"
164+
},
165+
/**
166+
* Configures how the .d.ts rollup file will be generated.
167+
*/
168+
"dtsRollup": {
169+
/**
170+
* (REQUIRED) Whether to generate the .d.ts rollup file.
171+
*/
172+
"enabled": false
173+
/**
174+
* Specifies the output path for a .d.ts rollup file to be generated without any trimming.
175+
* This file will include all declarations that are exported by the main entry point.
176+
*
177+
* If the path is an empty string, then this file will not be written.
178+
*
179+
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
180+
* prepend a folder token such as "<projectFolder>".
181+
*
182+
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
183+
* DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
184+
*/
185+
// "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
186+
/**
187+
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
188+
* This file will include only declarations that are marked as "@public" or "@beta".
189+
*
190+
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
191+
* prepend a folder token such as "<projectFolder>".
192+
*
193+
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
194+
* DEFAULT VALUE: ""
195+
*/
196+
// "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
197+
/**
198+
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
199+
* This file will include only declarations that are marked as "@public".
200+
*
201+
* If the path is an empty string, then this file will not be written.
202+
*
203+
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
204+
* prepend a folder token such as "<projectFolder>".
205+
*
206+
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
207+
* DEFAULT VALUE: ""
208+
*/
209+
// "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
210+
/**
211+
* When a declaration is trimmed, by default it will be replaced by a code comment such as
212+
* "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the
213+
* declaration completely.
214+
*
215+
* DEFAULT VALUE: false
216+
*/
217+
// "omitTrimmingComments": true
218+
},
219+
/**
220+
* Configures how the tsdoc-metadata.json file will be generated.
221+
*/
222+
"tsdocMetadata": {
223+
/**
224+
* Whether to generate the tsdoc-metadata.json file.
225+
*
226+
* DEFAULT VALUE: true
227+
*/
228+
// "enabled": true,
229+
/**
230+
* Specifies where the TSDoc metadata file should be written.
231+
*
232+
* The path is resolved relative to the folder of the config file that contains the setting; to change this,
233+
* prepend a folder token such as "<projectFolder>".
234+
*
235+
* The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
236+
* "typings" or "main" fields of the project's package.json. If none of these fields are set, the lookup
237+
* falls back to "tsdoc-metadata.json" in the package folder.
238+
*
239+
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
240+
* DEFAULT VALUE: "<lookup>"
241+
*/
242+
// "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
243+
},
244+
/**
245+
* Specifies what type of newlines API Extractor should use when writing output files. By default, the output files
246+
* will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead.
247+
* To use the OS's default newline kind, specify "os".
248+
*
249+
* DEFAULT VALUE: "crlf"
250+
*/
251+
// "newlineKind": "crlf",
252+
/**
253+
* Configures how API Extractor reports error and warning messages produced during analysis.
254+
*
255+
* There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages.
256+
*/
257+
"messages": {
258+
/**
259+
* Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
260+
* the input .d.ts files.
261+
*
262+
* TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551"
263+
*
264+
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
265+
*/
266+
"compilerMessageReporting": {
267+
/**
268+
* Configures the default routing for messages that don't match an explicit rule in this table.
269+
*/
270+
"default": {
271+
/**
272+
* Specifies whether the message should be written to the the tool's output log. Note that
273+
* the "addToApiReportFile" property may supersede this option.
274+
*
275+
* Possible values: "error", "warning", "none"
276+
*
277+
* Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail
278+
* and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes
279+
* the "--local" option), the warning is displayed but the build will not fail.
280+
*
281+
* DEFAULT VALUE: "warning"
282+
*/
283+
"logLevel": "warning"
284+
/**
285+
* When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md),
286+
* then the message will be written inside that file; otherwise, the message is instead logged according to
287+
* the "logLevel" option.
288+
*
289+
* DEFAULT VALUE: false
290+
*/
291+
// "addToApiReportFile": false
292+
}
293+
// "TS2551": {
294+
// "logLevel": "warning",
295+
// "addToApiReportFile": true
296+
// },
297+
//
298+
// . . .
299+
},
300+
/**
301+
* Configures handling of messages reported by API Extractor during its analysis.
302+
*
303+
* API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag"
304+
*
305+
* DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
306+
*/
307+
"extractorMessageReporting": {
308+
"default": {
309+
"logLevel": "warning"
310+
// "addToApiReportFile": false
311+
}
312+
// "ae-extra-release-tag": {
313+
// "logLevel": "warning",
314+
// "addToApiReportFile": true
315+
// },
316+
//
317+
// . . .
318+
},
319+
/**
320+
* Configures handling of messages reported by the TSDoc parser when analyzing code comments.
321+
*
322+
* TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text"
323+
*
324+
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
325+
*/
326+
"tsdocMessageReporting": {
327+
"default": {
328+
"logLevel": "warning"
329+
// "addToApiReportFile": false
330+
}
331+
// "tsdoc-link-tag-unescaped-text": {
332+
// "logLevel": "warning",
333+
// "addToApiReportFile": true
334+
// },
335+
//
336+
// . . .
337+
}
338+
}
339+
}

0 commit comments

Comments
 (0)