refactor(theme-registry): simplify docs build pipeline

refresh react-dogen types
remove unused jsdoc parser code

packages/__docs__/buildScripts/DataTypes.mts

@@ -28,7 +28,7 @@ import { Documentation } from 'react-docgen'
 type ProcessedFile =
   Documentation &
   YamlMetaInfo &
-  ParsedJSDoc &
+  JsDocResult &
   PackagePathData &
   { title: string, id:string }
 
@@ -60,23 +60,30 @@ type YamlMetaInfo = {
   tags?: string
 }
 
-type ParsedJSDoc = {
+type JsDocResult = {
+  // the comment section above the function
   comment?: string,
+  // metadata about the parsed file like filename
   meta?: any,
+  // the comment without the comment characters ("/*" etc)
   description?: string,
   kind?: string,
   name?: string,
+  // function params. undefined if the comment is e.g. above imports
   params?: {
     description?: string
     defaultValue?: string | number | boolean
     name: string
     type?: { names: string[] }
     optional?: boolean
   }[],
+  // function return value. undefined if the comment is e.g. above imports
   returns?: JSDocFunctionReturns[],
-  longName?: string,
-  sections?: any[],
-  undocumented?: boolean
+  //e.g. "module:debounce", "module:FocusRegion"
+  longname: string,
+  access?: string,
+  undocumented?: boolean,
+  title?: string
 }
 
 type JSDocFunctionReturns = {
@@ -85,77 +92,61 @@ type JSDocFunctionReturns = {
     names: string[]
   }
 }
-// TODO remove these types, now we can get them directly from react-docgen
+// TODO these are from React-docgen Documentation.d.ts,
+// remove when react-docgen exports them
 interface MethodParameter {
-  name: string
-  type?: TypeDescriptor | null
-  optional?: boolean
+  name: string;
+  description?: string;
+  optional: boolean;
+  type?: TypeDescriptor<FunctionSignatureType> | null;
 }
 
 interface MethodReturn {
-  type: TypeDescriptor | undefined
+  description?: string;
+  type: TypeDescriptor<FunctionSignatureType> | undefined;
 }
 
 interface PropDescriptor {
-  type?: PropTypeDescriptor
-  flowType?: TypeDescriptor
-  tsType?: TypeDescriptor<TSFunctionSignatureType>
-  required?: boolean
-  defaultValue?: any
-  description?: string
+  type?: PropTypeDescriptor;
+  flowType?: TypeDescriptor<FunctionSignatureType>;
+  tsType?: TypeDescriptor<TSFunctionSignatureType>;
+  required?: boolean;
+  defaultValue?: DefaultValueDescriptor;
+  description?: string;
 }
 
 interface PropTypeDescriptor {
-  name:
-    | 'arrayOf'
-    | 'custom'
-    | 'enum'
-    | 'array'
-    | 'bool'
-    | 'func'
-    | 'number'
-    | 'object'
-    | 'string'
-    | 'any'
-    | 'element'
-    | 'node'
-    | 'symbol'
-    | 'objectOf'
-    | 'shape'
-    | 'exact'
-    | 'union'
-    | 'elementType'
-    | 'instanceOf'
-  value?: any
-  raw?: string
-  computed?: boolean
-  // These are only needed for shape/exact types.
-  // Consider consolidating PropTypeDescriptor and PropDescriptor
-  description?: string
-  required?: boolean
+  name: 'any' | 'array' | 'arrayOf' | 'bool' | 'custom' | 'element' | 'elementType' | 'enum' | 'exact' | 'func' | 'instanceOf' | 'node' | 'number' | 'object' | 'objectOf' | 'shape' | 'string' | 'symbol' | 'union';
+  value?: unknown;
+  raw?: string;
+  computed?: boolean;
+  description?: string;
+  required?: boolean;
 }
 
-type TypeDescriptor<T = FunctionSignatureType> =
-  | SimpleType
-  | LiteralType
-  | ElementsType<T>
-  | ObjectSignatureType<T>
-  | T
+type TypeDescriptor<T = FunctionSignatureType> = ElementsType<T> | LiteralType | ObjectSignatureType<T> | SimpleType | T;
 
+interface DefaultValueDescriptor {
+  value: unknown;
+  computed: boolean;
+}
+interface BaseType {
+  required?: boolean;
+  nullable?: boolean;
+  alias?: string;
+}
 interface SimpleType extends BaseType {
-  name: string
-  raw?: string
+  name: string;
+  raw?: string;
 }
-
 interface LiteralType extends BaseType {
-  name: 'literal'
-  value: string
+  name: 'literal';
+  value: string;
 }
-
 interface ElementsType<T = FunctionSignatureType> extends BaseType {
-  name: string
-  raw: string
-  elements: Array<TypeDescriptor<T>>
+  name: string;
+  raw: string;
+  elements: Array<TypeDescriptor<T>>;
 }
 
 interface FunctionArgumentType<T> {
@@ -165,40 +156,33 @@ interface FunctionArgumentType<T> {
 }
 
 interface FunctionSignatureType extends BaseType {
-  name: 'signature'
-  type: 'function'
-  raw: string
+  name: 'signature';
+  type: 'function';
+  raw: string;
   signature: {
-    arguments: Array<FunctionArgumentType<FunctionSignatureType>>
-    return: TypeDescriptor
-  }
+    arguments: Array<FunctionArgumentType<FunctionSignatureType>>;
+    return?: TypeDescriptor<FunctionSignatureType>;
+  };
 }
-
 interface TSFunctionSignatureType extends FunctionSignatureType {
   signature: {
-    arguments: Array<FunctionArgumentType<TSFunctionSignatureType>>
-    return: TypeDescriptor<TSFunctionSignatureType>
-    this?: TypeDescriptor<TSFunctionSignatureType>
-  }
+    arguments: Array<FunctionArgumentType<TSFunctionSignatureType>>;
+    return?: TypeDescriptor<TSFunctionSignatureType>;
+    this?: TypeDescriptor<TSFunctionSignatureType>;
+  };
 }
-
 interface ObjectSignatureType<T = FunctionSignatureType> extends BaseType {
-  name: 'signature'
-  type: 'object'
-  raw: string
+  name: 'signature';
+  type: 'object';
+  raw: string;
   signature: {
     properties: Array<{
-      key: string | TypeDescriptor<T>
-      value: TypeDescriptor<T>
-    }>
-    constructor?: TypeDescriptor<T>
-  }
-}
-
-interface BaseType {
-  required?: boolean
-  nullable?: boolean
-  alias?: string
+      key: TypeDescriptor<T> | string;
+      value: TypeDescriptor<T>;
+      description?: string;
+    }>;
+    constructor?: TypeDescriptor<T>;
+  };
 }
 // end react-docgen part
 
@@ -285,5 +269,5 @@ export type {
   IconGlyph,
   MainDocsData,
   MainIconsData,
-  ParsedJSDoc
+  JsDocResult
 }

packages/__docs__/buildScripts/utils/getJSDoc.mts

@@ -25,28 +25,29 @@
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore no typing :(
 import jsdoc from 'jsdoc-api'
-import type { ParsedJSDoc } from '../DataTypes.mjs'
+import type { JsDocResult } from '../DataTypes.mts'
 
 export function getJSDoc(source: Buffer, error: (err: Error) => void) {
-  let doc: ParsedJSDoc = {}
+  // note: JSDoc seems to be abandoned, we should use TypeScript:
+  // https://stackoverflow.com/questions/47429792/is-it-possible-to-get-comments-as-nodes-in-the-ast-using-the-typescript-compiler
+  let doc: Partial<JsDocResult> = {}
   try {
-    const sections = jsdoc
+    // JSDoc only creates these sections if the file has a @module or @namespace annotation
+    let sections: JsDocResult[] = jsdoc
       .explainSync({
         // note: Do not use cache:true here, its buggy
         configure: './jsdoc.config.json',
         source
       })
-      .filter((section: Record<string, any>) => {
+      sections = sections.filter((section) => {
         return (
           section.undocumented !== true &&
           section.access !== 'private' &&
           section.kind !== 'package'
         )
       })
     const module =
-      sections.filter(
-        (section: Record<string, any>) => section.kind === 'module'
-      )[0] ||
+      sections.filter((section) => section.kind === 'module')[0] ||
       sections[0] ||
       {}
     if (process.platform === 'win32' && module.description) {
@@ -55,18 +56,6 @@ export function getJSDoc(source: Buffer, error: (err: Error) => void) {
     }
     doc = {
       ...module,
-      sections: sections
-        .filter(
-          (section: Record<string, any>) => section.longname !== module.longname
-        )
-        .map((section: Record<string, any>) => {
-          const name = section.longname.replace(`${module.longname}.`, '')
-          return {
-            ...section,
-            id: name,
-            title: name
-          }
-        }),
       undocumented: sections.length <= 0
     }
   } catch (err: any) {

packages/__docs__/buildScripts/utils/parseDoc.mts

@@ -26,14 +26,14 @@ import { getJSDoc } from './getJSDoc.mjs'
 import { getReactDoc } from './getReactDoc.mjs'
 import { getFrontMatter } from './getFrontMatter.mjs'
 import path from 'path'
-import type { ParsedJSDoc, YamlMetaInfo } from '../DataTypes.mjs'
+import type { JsDocResult, YamlMetaInfo } from '../DataTypes.mjs'
 import type { Documentation } from 'react-docgen'
 
 export function parseDoc(
   resourcePath: string,
   source: Buffer,
   errorHandler: (err: Error) => void
-): Documentation & YamlMetaInfo & ParsedJSDoc {
+): Documentation & YamlMetaInfo & Partial<JsDocResult> {
   const extension = path.extname(resourcePath)
   const allowedExtensions = ['.js', '.ts', '.tsx']
   let doc: Documentation | undefined

packages/__docs__/src/Document/index.tsx

@@ -361,31 +361,6 @@ import { ${importName} } from '${esPath}'
         )
     }
 
-    let sections
-
-    if (doc.sections) {
-      sections = doc.sections.map((section) => (
-        <View
-          margin="small 0"
-          display="block"
-          key={`${doc.id}.${section.name}`}
-        >
-          <Heading
-            level="h2"
-            as="h3"
-            color="secondary"
-            id={`${doc.id}.${section.name}`}
-            margin="large 0 small 0"
-          >
-            {section.kind && <code>{section.kind}</code>}
-            {section.title}
-          </Heading>
-          {this.renderDescription(section, section.description)}
-          {this.renderDetails(section)}
-        </View>
-      ))
-    }
-
     return (
       <div
         ref={(e) => {
@@ -396,7 +371,6 @@ import { ${importName} } from '${esPath}'
         {pageRef && <TableOfContents doc={doc} pageElement={pageRef} />}
         {this.renderDescription(doc, this.props.description)}
         {details}
-        {sections}
         {['.js', '.ts', '.tsx'].includes(doc.extension) && this.renderUsage()}
         {this.renderEditOnGithub()}
         {repository && layout !== 'small' && (

packages/__docs__/src/Properties/index.tsx

@@ -90,7 +90,7 @@ class Properties extends Component<PropertiesProps> {
               <code>{name}</code>
             </Table.Cell>
             <Table.Cell>
-              <code>{this.renderTSType(prop.tsType!)}</code>
+              {prop.tsType && <code>{this.renderTSType(prop.tsType)}</code>}
             </Table.Cell>
             <Table.Cell>{this.renderDefault(prop)}</Table.Cell>
             <Table.Cell>{this.renderDescription(prop)}</Table.Cell>
@@ -158,7 +158,8 @@ class Properties extends Component<PropertiesProps> {
     if (prop.required) {
       return <span css={styles?.required}>Required</span>
     } else if (prop.defaultValue) {
-      let defaultValue: string | React.ReactNode = prop.defaultValue.value
+      let defaultValue: string | React.ReactNode = prop.defaultValue
+        .value as string
       if (defaultValue === '() => {}') {
         defaultValue = <span css={styles?.noWrap}>{defaultValue}</span>
       }

packages/theme-registry/src/ThemeRegistry.ts

@@ -27,7 +27,7 @@
  * category: utilities/themes
  * ---
  * A global theme registry used for registering theme objects, setting globally available themes
- * and recieving the currently used theme.
+ * and receiving the currently used theme.
  * @module ThemeRegistry
  */