Add docs to types

syntax-tree · Jan 3, 2023 · b1e81c6 · b1e81c6
1 parent ab4dc20
commit b1e81c6
Showing 1 changed file with 48 additions and 42 deletions.
diff --git a/lib/index.js b/lib/index.js
@@ -1,43 +1,49 @@
 /**
- * @typedef {import('hast').Parent} Parent
  * @typedef {import('hast').Root} Root
+ * @typedef {import('hast').Content} Content
  * @typedef {import('hast').Element} Element
  * @typedef {import('hast').Properties} Properties
- * @typedef {Parent['children'][number]|Root} Node
+ * @typedef {Content | Root} Node
  *
  * @typedef {Properties[string]} PropertyValue
- *   Possible property values
- * @typedef {string|number|boolean} PrimitivePropertyValue
- *   Possible primitive HTML attribute values
- * @typedef {string|[string, ...Array<PrimitivePropertyValue|RegExp>]} AttributeValue
- * @typedef {Record<string, Array<PrimitivePropertyValue|RegExp>>} AttributeMap
+ *   Possible property values.
+ * @typedef {string | number | boolean} PrimitivePropertyValue
+ *   Possible primitive HTML attribute values.
  *
- * @typedef Schema Sanitization configuration
- * @property {Record<string, Array<AttributeValue>>} [attributes]
- *   Map of tag names to allowed property names. The special '*' key defines property names allowed on all elements
- * @property {Record<string, Record<string, PropertyValue>>} [required]
- *   Map of tag names to required property names and their default property value
- * @property {Array<string>} [tagNames]
- *   List of allowed tag names
- * @property {Record<string, Array<string>>} [protocols]
- *   Map of protocols to allow in property values
- * @property {Record<string, Array<string>>} [ancestors]
- *   Map of tag names to their required ancestor elements
- * @property {Array<string>} [clobber]
- *   List of allowed property names which can clobber
- * @property {string} [clobberPrefix]
- *   Prefix to use before potentially clobbering property names
- * @property {Array<string>} [strip]
- *   Names of elements to strip from the tree
- * @property {boolean} [allowComments]
- *   Whether to allow comments
- * @property {boolean} [allowDoctypes]
- *   Whether to allow doctypes
+ * @typedef {Record<string, Array<string | [string, ...Array<PrimitivePropertyValue | RegExp>]>>} Attributes
+ *  Map of tag names to allow lists for each property.
+ * @typedef {Record<string, Array<PrimitivePropertyValue | RegExp>>} AttributeClean
+ *   Normalized input.
+ *
+ * @typedef Schema
+ *   Sanitization configuration.
+ * @property {Attributes | undefined} [attributes]
+ *   Map of tag names to allowed properties.
+ *
+ *   The special `'*'` key defines property names allowed on all elements.
+ * @property {Record<string, Record<string, PropertyValue>> | undefined} [required]
+ *   Map of tag names to required property names and their default property value.
+ * @property {Array<string> | undefined} [tagNames]
+ *   List of allowed tag names.
+ * @property {Record<string, Array<string>> | undefined} [protocols]
+ *   Map of protocols to allow in property values.
+ * @property {Record<string, Array<string>> | undefined} [ancestors]
+ *   Map of tag names to their required ancestor elements.
+ * @property {Array<string> | undefined} [clobber]
+ *   List of allowed property names which can clobber.
+ * @property {string | undefined} [clobberPrefix]
+ *   Prefix to use before potentially clobbering property names.
+ * @property {Array<string> | undefined} [strip]
+ *   Names of elements to strip from the tree.
+ * @property {boolean | undefined} [allowComments]
+ *   Whether to allow comments.
+ * @property {boolean | undefined} [allowDoctypes]
+ *   Whether to allow doctypes.
  *
  * @typedef {(schema: Schema, value: any, node: any, stack: Array<string>) => unknown} Handler
  * @typedef {Record<string, Handler>} NodeDefinition
- * @typedef {((schema: Schema, node: Node) => NodeDefinition|undefined)} NodeDefinitionGetter
- * @typedef {Record<string, NodeDefinition|NodeDefinitionGetter>} NodeSchema
+ * @typedef {((schema: Schema, node: Node) => NodeDefinition | undefined)} NodeDefinitionGetter
+ * @typedef {Record<string, NodeDefinition | NodeDefinitionGetter>} NodeSchema
  */
 
 import {defaultSchema} from './schema.js'
@@ -100,18 +106,18 @@ export function sanitize(node, schema) {
  * @param {Schema} schema
  * @param {Node} node
  * @param {Array<string>} stack
- * @returns {Node|Array<Node>|undefined}
+ * @returns {Node | Array<Node> | undefined}
  */
 function one(schema, node, stack) {
   const type = node && node.type
   /** @type {Node} */
   // @ts-expect-error rest of props added later.
   const replacement = {type: node.type}
-  /** @type {boolean|undefined} */
+  /** @type {boolean | undefined} */
   let replace
 
   if (own.call(nodeSchema, type)) {
-    /** @type {NodeDefinition|NodeDefinitionGetter|undefined} */
+    /** @type {NodeDefinition | NodeDefinitionGetter | undefined} */
     let definition = nodeSchema[type]
 
     if (typeof definition === 'function') {
@@ -236,7 +242,7 @@ function handleProperties(schema, properties, node, stack) {
   for (key in props) {
     if (own.call(props, key)) {
       let value = props[key]
-      /** @type {Array<PrimitivePropertyValue|RegExp>} */
+      /** @type {AttributeClean[string]} */
       let definition
 
       if (own.call(allowed, key)) {
@@ -285,7 +291,7 @@ function handleDoctypeName() {
  * @param {string} tagName
  * @param {Node} _
  * @param {Array<string>} stack
- * @returns {string|false}
+ * @returns {string | false}
  */
 function handleTagName(schema, tagName, _, stack) {
   const name = typeof tagName === 'string' ? tagName : ''
@@ -355,12 +361,12 @@ function allow(_, value) {
  * @param {Schema} schema
  * @param {Array<unknown>} values
  * @param {string} prop
- * @param {Array<PrimitivePropertyValue|RegExp>} definition
- * @returns {Array<string|number>}
+ * @param {AttributeClean[string]} definition
+ * @returns {Array<string | number>}
  */
 function handlePropertyValues(schema, values, prop, definition) {
   let index = -1
-  /** @type {Array<string|number>} */
+  /** @type {Array<string | number>} */
   const result = []
 
   while (++index < values.length) {
@@ -381,7 +387,7 @@ function handlePropertyValues(schema, values, prop, definition) {
  * @param {Schema} schema
  * @param {unknown} value
  * @param {string} prop
- * @param {Array<PropertyValue|RegExp>} definition
+ * @param {AttributeClean[string]} definition
  * @returns {PropertyValue}
  */
 function handlePropertyValue(schema, value, prop, definition) {
@@ -451,11 +457,11 @@ function safeProtocol(schema, value, prop) {
 /**
  * Create a map from a list of props or a list of properties and values.
  *
- * @param {Array<AttributeValue>} values
- * @returns {AttributeMap}
+ * @param {Attributes[string]} values
+ * @returns {AttributeClean}
  */
 function toPropertyValueMap(values) {
-  /** @type {AttributeMap} */
+  /** @type {AttributeClean} */
   const result = {}
   let index = -1