Comments (7)
@iclanton started a PR #139 to implement this.
However, when the playground tries to render DocHtmlStartTag
and DocHtmlEndTag
as React virtual DOM, there isn't any way to render half of a tag. There's a proposal for React.Fragment
to support dangerouslySetInnerHTML , but it's not implemented yet. (API Extractor never encountered this problem because it renders TSDoc as Markdown instead of React, so we can simply append arbitrary text to the markdown string ignoring the tree structure.)
We considered trying to match up DocHtmlStartTag
and DocHtmlEndTag
during rendering, so we could create a corresponding React element, and then reattach the appropriate child nodes. But that seems messy. We realized that the TSDoc parser itself can do this fairly easily, if we require the input HTML to be well-formed XML instead of the messy ad hoc structures that CommonMark allows. This appeals to me, because when people need to embed nesting metadata in TSDoc, I generally recommend HTML5 custom elements instead of custom TSDoc inline tags, since XML is by design extensible and interoperable, whereas inline tags use a highly proprietary syntax.
Thus, I'm proposing to replace DocHtmlStartTag
and DocHtmlEndTag
in the TSDoc API with a new class called DocXmlElement
. This will make HTML elements "first class" citizens in the TSDoc spec, and make them easier for documentation tools to work with.
from tsdoc.
I wanted to enable general HTML tags, however for security reasons it requires a script sanitizer such as sanitize-html or xss. @iclanton could we add that to the loader?
from tsdoc.
dompurify looks to be more self-contained, and is hosted by cdnjs.com.
from tsdoc.
Hi @octogonz, I would be interested in implementing a DocXmlElement
. However, I have few specific questions:
Would we still want to store the opening and closing delimiters for both the start and end tags within DocXmlElement
or just store the start tag and end tag excerpts?
Would a DocXmlElement
extend a DocNodeContainer
? From a semantics point-of-view, XML nodes can only contain other xml nodes (or plain text), having any other tsdoc tags within them is invalid.
BuiltInNodes
validates this anyways so I would assume DocNodeContainer
would suffice.
Finally in the case of plain text within an XML node (<foo>hello world!</foo>
), should we introduce another DocXmlPlainText
class to represent these children?
from tsdoc.
Hey @suneettipirneni, that would be awesome to finally get this implemented! I haven't thought about it in a long time.
Would we still want to store the opening and closing delimiters for both the start and end tags within
DocXmlElement
or just store the start tag and end tag excerpts?
Hmm... I haven't thought about this in a long time. 🙂 I think the AST is designed with excerpts as the leaf nodes, so it would be something like this:
Sample input:
<a>hi<b /></a>
AST pseudocode:
- DocXmlElement
* excerpts for: "<a>"
- DocPlainText
* excerpts for: "hi"
- DocXmlElement
* excerpts for: "<b />"
* excerpts for: "</a>"
Note that "</a>"
is an excerpt belonging to the root DocXmlElement
.
An AST visitor would be interested in the meaningful nodes DocXmlElement
, DocPlainText
, etc, whereas the excerpts are extra coordinates used for only for specialized operations such as syntax highlighting, or surgically modifying a document while preserving its original formatting.
BuiltInNodes
validates this anyways so I would assumeDocNodeContainer
would suffice.
Yes, it would be a DocNodeContainer
with those constraints. A key idea of DocNodeContainer
is that it's possible for a user to introduce custom nodes that adjust these constraints. Some examples here: api-documenter/src/nodes/CustomDocNodeKind.ts
Finally in the case of plain text within an XML node (
<foo>hello world!</foo>
), should we introduce anotherDocXmlPlainText
class to represent these children?
Yes.
Also keep in mind that the AST is intended to represent syntax errors as well, faithfully enough that it can regenerate the original input. Consider this example:
/**
* <a>b</c>
*/
Maybe it would get represented as:
- (parent)
- DocXmlElement
* excerpts for: "<a>"
- DocPlainText
* excerpts for: "b"
- DocXmlElement
* excerpts for: "</c>"
Here "b"
becomes a sibling of <a>
instead of a child, and </c>
is a degenerate DocXmlElement
representing only an orphaned closing tag. (Or maybe </c>
is DocErrorText
? It depends on how much of the structure is useful, for example maybe we still want to syntax highlight </c>
correctly.)
A web HTML parser has quite sophisticated heuristics that would try to render a sensible web page from broken syntax, for example inferring </a>
so that b
can be a child of <a>
. But TSDoc doesn't need to worry about that in my opinion. Our priority is to implement a behavior that is simple and predictable and intuitive. (We don't face the problem of cross-compatibility with Chrome/Firefox/Safari/IE/etc specifically because TSDoc intends to be a strict standard with well-defined grammar rules, more like XML than HTML.)
from tsdoc.
Hi @octogonz, I made a draft pr for this. If you could give me any feedback on this initial implementation, it would be greatly appreciated 😄.
from tsdoc.
Much appreciated! I apologize for the slow response -- I've been really busy this week. I will take a look over the weekend. Thanks for patience!
from tsdoc.
Related Issues (20)
- Upgrade Node.js and `node-sass` dependencies HOT 1
- Validate invalid params through tsdoc eslint plugin HOT 1
- This repo is missing important files
- Documentation coverage? HOT 1
- JSDoc/TSDoc `@inherit[dD]oc` mismatch HOT 1
- Is it dead? HOT 4
- VS Code unable to load Schema
- tsdoc-unnecessary-backslash false positive
- Weird warnings about multiple declarations HOT 1
- Grouping classes under the same index name
- Support for defining custom tag syntax HOT 1
- tsdoc-html-tag-missing-equals erroneously flagging boolean attributes
- tsdoc-malformed-html-name erroneously flagging use of less than symbol HOT 1
- Unable to load schema from 'https://json.schemastore.org/tsconfig HOT 1
- `tsdoc-reference-unquoted-identifier` is incorrectly reported for certain identifiers
- [ Question ][ Playground ] Intended Behaviour? HOT 2
- eslint-plugin-tsdoc: Missing rule to check for absence of a TSDoc comment HOT 1
- ESLint flat configurations? HOT 1
- "extends": "@rushstack/heft-node-rig/profiles/default/config/jest.config.json"
- Can inherit doc also copy the TSDoc when I hover?
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from tsdoc.