Skip to content

Commit dd5ea09

Browse files
AndrewJakubowiczAndrewJakubowicz
committed
Fix TypeDoc generation of reflected types and accessors.
Tested by checking `observedAttributes` docs and `updateComplete`
1 parent 32e1786 commit dd5ea09

File tree

2 files changed

+118
-7
lines changed

2 files changed

+118
-7
lines changed

‎packages/lit-dev-api/api-data/lit-2/pages.json

Lines changed: 106 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,14 @@
167167
"flags": {
168168
"isStatic": true
169169
},
170+
"comment": {
171+
"blockTags": [
172+
{
173+
"tag": "@nocollapse"
174+
}
175+
],
176+
"shortText": "Returns a list of attributes corresponding to the registered properties."
177+
},
170178
"sources": [
171179
{
172180
"fileName": "packages/reactive-element/src/reactive-element.ts",
@@ -369,6 +377,15 @@
369377
"isStatic": true,
370378
"isOptional": true
371379
},
380+
"comment": {
381+
"blockTags": [
382+
{
383+
"tag": "@nocollapse"
384+
}
385+
],
386+
"shortText": "Disable the given warning category for this class.",
387+
"text": "This method only exists in development builds, so it should be accessed\nwith a guard like:\n```ts\n// Disable for all ReactiveElement subclasses\nReactiveElement.disableWarning?.('migration');\n// Disable for only MyElement and subclasses\nMyElement.disableWarning?.('migration');\n```\n"
388+
},
372389
"sources": [
373390
{
374391
"fileName": "packages/reactive-element/src/reactive-element.ts",
@@ -505,6 +522,15 @@
505522
"isStatic": true,
506523
"isOptional": true
507524
},
525+
"comment": {
526+
"blockTags": [
527+
{
528+
"tag": "@nocollapse"
529+
}
530+
],
531+
"shortText": "Enable the given warning category for this class.",
532+
"text": "This method only exists in development builds, so it should be accessed\nwith a guard like:\n```ts\n// Enable for all ReactiveElement subclasses\nReactiveElement.enableWarning?.('migration');\n// Enable for only MyElement and subclasses\nMyElement.enableWarning?.('migration');\n```\n"
533+
},
508534
"sources": [
509535
{
510536
"fileName": "packages/reactive-element/src/reactive-element.ts",
@@ -2474,12 +2500,13 @@
24742500
"tag": "@returns",
24752501
"content": [
24762502
{
2477-
"text": "A promise of a boolean that indicates if the update resolved\n without triggering another update."
2503+
"text": "A promise of a boolean that resolves to true if the update completed\n without triggering another update."
24782504
}
24792505
]
24802506
}
24812507
],
2482-
"shortText": "Returns a Promise that resolves when the host has completed updating.\nThe Promise value is a boolean that is `true` if the element completed the\nupdate without triggering another update. The Promise result is `false` if\na property was set inside `updated()`. If the Promise is rejected, an\nexception was thrown during the update."
2508+
"shortText": "Returns a Promise that resolves when the element has completed updating.\nThe Promise value is a boolean that is `true` if the element completed the\nupdate without triggering another update. The Promise result is `false` if\na property was set inside `updated()`. If the Promise is rejected, an\nexception was thrown during the update.",
2509+
"text": "To await additional asynchronous work, override the `getUpdateComplete`\nmethod. For example, it is sometimes useful to await a rendered element\nbefore fulfilling this Promise. To do this, first await\n`super.getUpdateComplete()`, then any subsequent state.\n"
24832510
},
24842511
"sources": [
24852512
{
@@ -3157,6 +3184,14 @@
31573184
"flags": {
31583185
"isStatic": true
31593186
},
3187+
"comment": {
3188+
"blockTags": [
3189+
{
3190+
"tag": "@nocollapse"
3191+
}
3192+
],
3193+
"shortText": "Returns a list of attributes corresponding to the registered properties."
3194+
},
31603195
"sources": [
31613196
{
31623197
"fileName": "packages/reactive-element/src/reactive-element.ts",
@@ -3347,6 +3382,15 @@
33473382
"isStatic": true,
33483383
"isOptional": true
33493384
},
3385+
"comment": {
3386+
"blockTags": [
3387+
{
3388+
"tag": "@nocollapse"
3389+
}
3390+
],
3391+
"shortText": "Disable the given warning category for this class.",
3392+
"text": "This method only exists in development builds, so it should be accessed\nwith a guard like:\n```ts\n// Disable for all ReactiveElement subclasses\nReactiveElement.disableWarning?.('migration');\n// Disable for only MyElement and subclasses\nMyElement.disableWarning?.('migration');\n```\n"
3393+
},
33503394
"sources": [
33513395
{
33523396
"fileName": "packages/reactive-element/src/reactive-element.ts",
@@ -3467,6 +3511,15 @@
34673511
"isStatic": true,
34683512
"isOptional": true
34693513
},
3514+
"comment": {
3515+
"blockTags": [
3516+
{
3517+
"tag": "@nocollapse"
3518+
}
3519+
],
3520+
"shortText": "Enable the given warning category for this class.",
3521+
"text": "This method only exists in development builds, so it should be accessed\nwith a guard like:\n```ts\n// Enable for all ReactiveElement subclasses\nReactiveElement.enableWarning?.('migration');\n// Enable for only MyElement and subclasses\nMyElement.enableWarning?.('migration');\n```\n"
3522+
},
34703523
"sources": [
34713524
{
34723525
"fileName": "packages/reactive-element/src/reactive-element.ts",
@@ -5101,12 +5154,13 @@
51015154
"tag": "@returns",
51025155
"content": [
51035156
{
5104-
"text": "A promise of a boolean that indicates if the update resolved\n without triggering another update."
5157+
"text": "A promise of a boolean that resolves to true if the update completed\n without triggering another update."
51055158
}
51065159
]
51075160
}
51085161
],
5109-
"shortText": "Returns a Promise that resolves when the host has completed updating.\nThe Promise value is a boolean that is `true` if the element completed the\nupdate without triggering another update. The Promise result is `false` if\na property was set inside `updated()`. If the Promise is rejected, an\nexception was thrown during the update."
5162+
"shortText": "Returns a Promise that resolves when the element has completed updating.\nThe Promise value is a boolean that is `true` if the element completed the\nupdate without triggering another update. The Promise result is `false` if\na property was set inside `updated()`. If the Promise is rejected, an\nexception was thrown during the update.",
5163+
"text": "To await additional asynchronous work, override the `getUpdateComplete`\nmethod. For example, it is sometimes useful to await a rendered element\nbefore fulfilling this Promise. To do this, first await\n`super.getUpdateComplete()`, then any subsequent state.\n"
51105164
},
51115165
"sources": [
51125166
{
@@ -6332,6 +6386,20 @@
63326386
{
63336387
"name": "SanitizerFactory",
63346388
"kindString": "Type alias",
6389+
"comment": {
6390+
"blockTags": [
6391+
{
6392+
"tag": "@returns",
6393+
"content": [
6394+
{
6395+
"text": "A function that will sanitize this class of writes."
6396+
}
6397+
]
6398+
}
6399+
],
6400+
"shortText": "Used to sanitize any value before it is written into the DOM. This can be\nused to implement a security policy of allowed and disallowed values in\norder to prevent XSS attacks.",
6401+
"text": "One way of using this callback would be to check attributes and properties\nagainst a list of high risk fields, and require that values written to such\nfields be instances of a class which is safe by construction. Closure's Safe\nHTML Types is one implementation of this technique (\nhttps://github.com/google/safe-html-types/blob/master/doc/safehtml-types.md).\nThe TrustedTypes polyfill in API-only mode could also be used as a basis\nfor this technique (https://github.com/WICG/trusted-types).\n"
6402+
},
63356403
"sources": [
63366404
{
63376405
"fileName": "packages/lit-html/src/lit-html.ts",
@@ -18395,6 +18463,9 @@
1839518463
{
1839618464
"name": "endNode",
1839718465
"kindString": "Accessor",
18466+
"comment": {
18467+
"shortText": "The part's trailing marker node, if any. See `.parentNode` for more\ninformation."
18468+
},
1839818469
"sources": [
1839918470
{
1840018471
"fileName": "packages/lit-html/src/lit-html.ts",
@@ -18455,6 +18526,10 @@
1845518526
{
1845618527
"name": "parentNode",
1845718528
"kindString": "Accessor",
18529+
"comment": {
18530+
"shortText": "The parent node into which the part renders its content.",
18531+
"text": "A ChildPart's content consists of a range of adjacent child nodes of\n`.parentNode`, possibly bordered by 'marker nodes' (`.startNode` and\n`.endNode`).\n- If both `.startNode` and `.endNode` are non-null, then the part's content\nconsists of all siblings between `.startNode` and `.endNode`, exclusively.\n- If `.startNode` is non-null but `.endNode` is null, then the part's\ncontent consists of all siblings following `.startNode`, up to and\nincluding the last child of `.parentNode`. If `.endNode` is non-null, then\n`.startNode` will always be non-null.\n- If both `.endNode` and `.startNode` are null, then the part's content\nconsists of all child nodes of `.parentNode`.\n"
18532+
},
1845818533
"sources": [
1845918534
{
1846018535
"fileName": "packages/lit-html/src/lit-html.ts",
@@ -18498,6 +18573,9 @@
1849818573
{
1849918574
"name": "startNode",
1850018575
"kindString": "Accessor",
18576+
"comment": {
18577+
"shortText": "The part's leading marker node, if any. See `.parentNode` for more\ninformation."
18578+
},
1850118579
"sources": [
1850218580
{
1850318581
"fileName": "packages/lit-html/src/lit-html.ts",
@@ -27516,6 +27594,9 @@
2751627594
{
2751727595
"name": "endNode",
2751827596
"kindString": "Accessor",
27597+
"comment": {
27598+
"shortText": "The part's trailing marker node, if any. See `.parentNode` for more\ninformation."
27599+
},
2751927600
"sources": [
2752027601
{
2752127602
"fileName": "packages/lit-html/src/lit-html.ts",
@@ -27588,6 +27669,10 @@
2758827669
{
2758927670
"name": "parentNode",
2759027671
"kindString": "Accessor",
27672+
"comment": {
27673+
"shortText": "The parent node into which the part renders its content.",
27674+
"text": "A ChildPart's content consists of a range of adjacent child nodes of\n`.parentNode`, possibly bordered by 'marker nodes' (`.startNode` and\n`.endNode`).\n- If both `.startNode` and `.endNode` are non-null, then the part's content\nconsists of all siblings between `.startNode` and `.endNode`, exclusively.\n- If `.startNode` is non-null but `.endNode` is null, then the part's\ncontent consists of all siblings following `.startNode`, up to and\nincluding the last child of `.parentNode`. If `.endNode` is non-null, then\n`.startNode` will always be non-null.\n- If both `.endNode` and `.startNode` are null, then the part's content\nconsists of all child nodes of `.parentNode`.\n"
27675+
},
2759127676
"sources": [
2759227677
{
2759327678
"fileName": "packages/lit-html/src/lit-html.ts",
@@ -27643,6 +27728,9 @@
2764327728
{
2764427729
"name": "startNode",
2764527730
"kindString": "Accessor",
27731+
"comment": {
27732+
"shortText": "The part's leading marker node, if any. See `.parentNode` for more\ninformation."
27733+
},
2764627734
"sources": [
2764727735
{
2764827736
"fileName": "packages/lit-html/src/lit-html.ts",
@@ -27806,6 +27894,20 @@
2780627894
{
2780727895
"name": "ValueSanitizer",
2780827896
"kindString": "Type alias",
27897+
"comment": {
27898+
"blockTags": [
27899+
{
27900+
"tag": "@returns",
27901+
"content": [
27902+
{
27903+
"text": "The value to write to the DOM. Usually the same as the input value,\n unless sanitization is needed."
27904+
}
27905+
]
27906+
}
27907+
],
27908+
"shortText": "A function which can sanitize values that will be written to a specific kind\nof DOM sink.",
27909+
"text": "See SanitizerFactory.\n"
27910+
},
2780927911
"sources": [
2781027912
{
2781127913
"fileName": "packages/lit-html/src/lit-html.ts",

‎packages/lit-dev-tools-cjs/src/api-docs/transformer.ts

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -334,14 +334,23 @@ export class ApiDocsTransformer {
334334
}
335335

336336
/**
337-
* For functions, TypeDoc put comments inside the signatures property, instead
338-
* of directly in the function node. Hoist these comments up so that we can
339-
* treat comments uniformly.
337+
* For functions, reflected types, and accessors, TypeDoc put comments inside
338+
* the signatures property, instead of directly in the function node. Hoist
339+
* these comments up so that we can treat comments uniformly.
340340
*/
341341
private promoteSignatureComments(node: DeclarationReflection) {
342+
// Handle functions
342343
if (!node.comment?.summary && node.signatures?.[0]?.comment?.summary) {
343344
node.comment = node.signatures[0].comment;
344345
}
346+
// Handle reflected types
347+
if (!node.comment?.summary && node.type?.type === "reflection") {
348+
node.comment = node.type.declaration?.signatures?.[0]?.comment;
349+
}
350+
// Handle accessors
351+
if (node.kindString === "Accessor" && node.getSignature?.comment) {
352+
node.comment = node.getSignature.comment;
353+
}
345354
}
346355

347356
/**

0 commit comments

Comments
 (0)