Add more docs to types

Author: wooorm

lib/core.js

@@ -1,25 +1,37 @@
 /**
  * @typedef {import('hast').Root} Root
+ * @typedef {import('hast').Content} Content
  * @typedef {import('hast').Element} Element
  * @typedef {import('hast').Properties} Properties
- * @typedef {Root['children'][number]} Child
- * @typedef {Child|Root} Node
  * @typedef {import('property-information').Info} Info
  * @typedef {import('property-information').Schema} Schema
+ */
+
+/**
+ * @typedef {Content | Root} Node
+ *   Any concrete `hast` node.
+ * @typedef {Root | Element} HResult
+ *   Result from a `h` (or `s`) call.
  *
- * @typedef {Root|Element} HResult
- * @typedef {string|number} HStyleValue
+ * @typedef {string | number} HStyleValue
+ *   Value for a CSS style field.
  * @typedef {Record<string, HStyleValue>} HStyle
- * @typedef {string|number|boolean|null|undefined} HPrimitiveValue
- * @typedef {Array<string|number>} HArrayValue
- * @typedef {HPrimitiveValue|HArrayValue} HPropertyValue
- * @typedef {{[property: string]: HPropertyValue|HStyle}} HProperties
- *   Acceptable properties value.
+ *   Supported value of a `style` prop.
+ * @typedef {string | number | boolean | null | undefined} HPrimitiveValue
+ *   Primitive property value.
+ * @typedef {Array<string | number>} HArrayValue
+ *   List of property values for space- or comma separated values (such as `className`).
+ * @typedef {HPrimitiveValue | HArrayValue} HPropertyValue
+ *   Primitive value or list value.
+ * @typedef {{[property: string]: HPropertyValue | HStyle}} HProperties
+ *   Acceptable value for element properties.
  *
- * @typedef {string|number|null|undefined} HPrimitiveChild
- * @typedef {Array<Node|HPrimitiveChild>} HArrayChild
- * @typedef {Node|HPrimitiveChild|HArrayChild} HChild
- *   Acceptable child value
+ * @typedef {string | number | null | undefined} HPrimitiveChild
+ *   Primitive children, either ignored (nullish), or turned into text nodes.
+ * @typedef {Array<Node | HPrimitiveChild>} HArrayChild
+ *   List of children.
+ * @typedef {Node | HPrimitiveChild | HArrayChild} HChild
+ *   Acceptable child value.
  */
 
 import {find, normalize} from 'property-information'
@@ -43,7 +55,7 @@ export function core(schema, defaultTagName, caseSensitive) {
     /**
      * @type {{
      *   (): Root
-     *   (selector: null|undefined, ...children: Array<HChild>): Root
+     *   (selector: null | undefined, ...children: Array<HChild>): Root
      *   (selector: string, properties?: HProperties, ...children: Array<HChild>): Element
      *   (selector: string, ...children: Array<HChild>): Element
      * }}
@@ -52,8 +64,8 @@ export function core(schema, defaultTagName, caseSensitive) {
       /**
        * Hyperscript compatible DSL for creating virtual hast trees.
        *
-       * @param {string|null} [selector]
-       * @param {HProperties|HChild} [properties]
+       * @param {string | null} [selector]
+       * @param {HProperties | HChild} [properties]
        * @param {Array<HChild>} children
        * @returns {HResult}
        */
@@ -108,7 +120,7 @@ export function core(schema, defaultTagName, caseSensitive) {
 }
 
 /**
- * @param {HProperties|HChild} value
+ * @param {HProperties | HChild} value
  * @param {string} name
  * @returns {value is HProperties}
  */
@@ -141,7 +153,7 @@ function isProperties(value, name) {
  * @param {Schema} schema
  * @param {Properties} properties
  * @param {string} key
- * @param {HStyle|HPropertyValue} value
+ * @param {HStyle | HPropertyValue} value
  * @returns {void}
  */
 function addProperty(schema, properties, key, value) {
@@ -181,7 +193,7 @@ function addProperty(schema, properties, key, value) {
   }
 
   if (Array.isArray(result)) {
-    /** @type {Array<string|number>} */
+    /** @type {Array<string | number>} */
     const finalResult = []
 
     while (++index < result.length) {
@@ -202,7 +214,7 @@ function addProperty(schema, properties, key, value) {
 }
 
 /**
- * @param {Array<Child>} nodes
+ * @param {Array<Content>} nodes
  * @param {HChild} value
  * @returns {void}
  */
@@ -254,8 +266,12 @@ function parsePrimitive(info, name, value) {
 }
 
 /**
+ * Serialize a `style` object as a string.
+ *
  * @param {HStyle} value
+ *   Style object.
  * @returns {string}
+ *   CSS string.
  */
 function style(value) {
   /** @type {Array<string>} */
@@ -273,8 +289,12 @@ function style(value) {
 }
 
 /**
+ * Create a map to adjust casing.
+ *
  * @param {Array<string>} values
+ *   List of properly cased keys.
  * @returns {Record<string, string>}
+ *   Map of lowercase keys to uppercase keys.
  */
 function createAdjustMap(values) {
   /** @type {Record<string, string>} */

lib/html.js

@@ -1,6 +1,10 @@
 /**
- * @typedef {import('./core.js').HChild} Child Acceptable child value
- * @typedef {import('./core.js').HProperties} Properties Acceptable properties value.
+ * @typedef {import('./core.js').HChild} Child
+ *   Acceptable child value.
+ * @typedef {import('./core.js').HProperties} Properties
+ *   Acceptable value for element properties.
+ * @typedef {import('./core.js').HResult} Result
+ *   Result from a `h` (or `s`) call.
  *
  * @typedef {import('./jsx-classic.js').Element} h.JSX.Element
  * @typedef {import('./jsx-classic.js').IntrinsicAttributes} h.JSX.IntrinsicAttributes

lib/index.js

@@ -1,7 +1,10 @@
 /**
  * @typedef {import('./core.js').HChild} Child
+ *   Acceptable child value.
  * @typedef {import('./core.js').HProperties} Properties
+ *   Acceptable value for element properties.
  * @typedef {import('./core.js').HResult} Result
+ *   Result from a `h` (or `s`) call.
  */
 
 export {h} from './html.js'

lib/runtime.js

@@ -8,23 +8,25 @@
  * @typedef {import('./core.js').HStyle} HStyle
  * @typedef {import('./core.js').core} Core
  *
- * @typedef {Record<string, HPropertyValue|HStyle|HChild>} JSXProps
+ * @typedef {Record<string, HPropertyValue | HStyle | HChild>} JSXProps
  */
 
 /**
+ * Create an automatic runtime.
+ *
  * @param {ReturnType<Core>} f
  */
 export function runtime(f) {
   const jsx =
     /**
      * @type {{
-     *   (type: null|undefined, props: {children?: HChild}, key?: string): Root
+     *   (type: null | undefined, props: {children?: HChild}, key?: string): Root
      *   (type: string, props: JSXProps, key?: string): Element
      * }}
      */
     (
       /**
-       * @param {string|null} type
+       * @param {string | null} type
        * @param {HProperties & {children?: HChild}} props
        * @returns {HResult}
        */

lib/svg.js

@@ -1,6 +1,10 @@
 /**
  * @typedef {import('./core.js').HChild} Child
+ *   Acceptable child value.
  * @typedef {import('./core.js').HProperties} Properties
+ *   Acceptable value for element properties.
+ * @typedef {import('./core.js').HResult} Result
+ *   Result from a `h` (or `s`) call.
  *
  * @typedef {import('./jsx-classic.js').Element} s.JSX.Element
  * @typedef {import('./jsx-classic.js').IntrinsicAttributes} s.JSX.IntrinsicAttributes