refactor: remove jsdoc-api from the docs app

wip, it does not parse some files for some reason

Author: matyasf

package-lock.json

@@ -62,36 +62,32 @@ type YamlMetaInfo = {
 }
 
 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,
+  // If it's a function it will be the function's name, otherwise
+  // it's either the string after the '@module' annotation or the variable's name
   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[] }
+    type?: string
+    defaultValue?: string
     optional?: boolean
+    // the description of the param
+    description?: string
   }[],
+  genericParameters?: {
+    name: string
+    defaultValue?: string
+    constraint?: string
+  }[]
   // function return value. undefined if the comment is e.g. above imports
-  returns?: JSDocFunctionReturns[],
-  //e.g. "module:debounce", "module:FocusRegion"
-  longname: string,
-  access?: string,
-  undocumented?: boolean,
-  title?: string
+  returns?: JSDocFunctionReturns,
 }
 
 type JSDocFunctionReturns = {
-  description: string
-  type: {
-    names: string[]
-  }
+  description?: string
+  type?: string
 }
 
 type LibraryOptions = {

packages/__docs__/buildScripts/DataTypes.mts

@@ -31,7 +31,7 @@ import { theme as canvasTheme } from '@instructure/canvas-theme'
 import { theme as canvasHighContrastTheme } from '@instructure/canvas-high-contrast-theme'
 import type {
   LibraryOptions,
-  MainDocsData,
+  MainDocsData, ProcessedFile
 } from './DataTypes.mjs'
 import { getFrontMatter } from './utils/getFrontMatter.mjs'
 import { createRequire } from "module"
@@ -119,6 +119,7 @@ if (import.meta.url === pathToFileURL(process.argv[1]).href) {
 function buildDocs() {
   // eslint-disable-next-line no-console
   console.log('Start building application data')
+  console.time('docs build time')
 
   const { COPY_VERSIONS_JSON = '1' } = process.env
   const shouldDoTheVersionCopy = Boolean(parseInt(COPY_VERSIONS_JSON))
@@ -133,12 +134,13 @@ function buildDocs() {
       console.log(
         'Parsing markdown and source files... (' + matches.length + ' files)'
       )
-      const docs = matches.map((relativePath) => {
+      let docs = matches.map((relativePath) => {
         // loop trough every source and Readme file
         return processSingleFile(path.resolve(relativePath))
       })
+      docs = docs.filter(Boolean) // filter out undefined
       const themes = parseThemes()
-      const clientProps = getClientProps(docs, library)
+      const clientProps = getClientProps(docs as ProcessedFile[], library)
       const props: MainDocsData = {
         ...clientProps,
         themes: themes,
@@ -158,6 +160,7 @@ function buildDocs() {
       console.log('Finished building documentation data')
     })
     .then(() => {
+      console.timeEnd('docs build time')
       if (shouldDoTheVersionCopy) {
         // eslint-disable-next-line no-console
         console.log('Copying versions.json into __build__ folder')
@@ -187,6 +190,9 @@ function processSingleFile(fullPath: string) {
   const fileName = path.parse(fullPath).name
   if (fileName === 'index') {
     docObject = processFile(fullPath, projectRoot, library)
+    if (!docObject) {
+      return
+    }
     // Some Components (e.g. Alert) store their descriptions in README.md files.
     // Add this to the final JSON if it's edited
     const readmeDesc = tryParseReadme(dirName)
@@ -202,7 +208,7 @@ function processSingleFile(fullPath: string) {
       componentIndexFile = path.join(dirName, 'index.ts')
     }
     if (componentIndexFile) {
-      docObject = processFile(componentIndexFile, projectRoot, library)
+      docObject = processFile(componentIndexFile, projectRoot, library)!
       const readmeDesc = tryParseReadme(dirName)
       docObject.description = readmeDesc ? readmeDesc : docObject.description
     } else {
@@ -213,9 +219,12 @@ function processSingleFile(fullPath: string) {
     // documentation .md files, utils ts and tsx files
     docObject = processFile(fullPath, projectRoot, library)
   }
-  const docJSON = JSON.stringify(docObject!)
-  fs.writeFileSync(buildDir + 'docs/' + docObject!.id + '.json', docJSON)
-  return docObject!
+  if (!docObject) {
+    return
+  }
+  const docJSON = JSON.stringify(docObject)
+  fs.writeFileSync(buildDir + 'docs/' + docObject.id + '.json', docJSON)
+  return docObject
 }
 
 function tryParseReadme(dirName: string) {

packages/__docs__/buildScripts/build-docs.mts

@@ -32,7 +32,7 @@ export function processFile(
   fullPath: string,
   projectRoot: string,
   library: LibraryOptions
-): ProcessedFile {
+): ProcessedFile | undefined {
   // eslint-disable-next-line no-console
   console.info(`Processing ${fullPath}`)
   const source = fs.readFileSync(fullPath)
@@ -42,6 +42,9 @@ export function processFile(
   const doc = parseDoc(fullPath, source, (err: Error) => {
     console.warn('Error when parsing ', fullPath, ":\n", err.stack)
   })
+  if (!doc) {
+    return
+  }
   const docData: ProcessedFile = { ...doc, ...pathInfo } as ProcessedFile
   // TODO docblock is always undefined. Either show this or delete.
   docData.methods = docData.methods

packages/__docs__/buildScripts/processFile.mts

@@ -44,9 +44,6 @@ export function getClientProps(docs: ProcessedFile[], library: LibraryOptions) {
     .filter((doc) => !doc.private)
     .forEach((doc) => {
       const { category, id, parent, describes } = doc
-      if (doc.undocumented) {
-        return
-      }
       // warn if the ID already exists with a different path
       if (docIDs[id] && docIDs[id] !== doc.srcPath) {
         warning(