Implement @webonly tag to exclude items from Node docs #1679
Conversation
scripts/docgen/generate-docs.js
Outdated
| if (item.tags) { | ||
| item.tags.forEach(tag => { | ||
| if (tag.tagName.escapedText === 'webonly') { | ||
| webOnlyBlocks.push({ start: node.pos, end: node.end }); |
There was a problem hiding this comment.
Is it possible to create a new AST by deleting "webonly" nodes? Then you can use AST.writefile or something similar to create a file instead of scanning the file and deleting lines.
There was a problem hiding this comment.
The native Typescript parser is pretty basic. It doesn't have a delete method and doesn't give direct access to children. There is a wrapper library that provides that functionality (https://github.com/dsherret/ts-morph) but I think it also does it by just removing text? I would use that library but it says prominently in several places it's WIP and I don't know how stable it is.
There was a problem hiding this comment.
Thanks for the help, updated the code to use the transformer as you suggested.
scripts/docgen/generate-docs.js
Outdated
| // } | ||
| // typescript.forEachChild(node, findWebOnlyBlocks); | ||
| // } | ||
| // findWebOnlyBlocks(typescriptSourceFile); |
There was a problem hiding this comment.
Should be removed, I think this snippet is from one commit behind?
Added a
@webonlytag. When included in leading comments inpackages/firebase/index.d.ts, it will exclude that symbol from Node docs. This happens by thegenerate-docs.jsscript creating a temporary copy ofindex.d.tsthat excludes any item with that tag. It uses the native Typescript parser to find these sections.@webonlymust be added after the description text of the comment, or Typedoc will think that text is part of the tag and exclude it. I'll add instructions on usage into `CONTRIBUTING.md`` in a separate PR.Also changed the order of signatures/descriptions for overloaded methods. Typedoc does S-S-S-D-D-D, users prefer S-D-S-D-S-D. May look into a future change to make descriptions collapsible.