build: fix docs generation after tsdoc 2.8 upgrade + updates

Author: ahochsteger

devbox.lock

@@ -51,7 +51,7 @@ Decrypt a PDF attachment and store it to a Google Drive location.<br />NOTE: PDF
 | `conflictStrategy` | `ConflictStrategy` | The strategy to be used in case a file already exists at the desired location. See [Enum Type `ConflictStrategy`](enum-types.mdx#conflictstrategy) for valid values. |
 | `description` | `string` | The description to be attached to the Google Drive file.<br />Supports [placeholder](placeholder.mdx) substitution. |
 | `location` | `string` | The location (path + filename) of the Google Drive file.<br />For shared folders or Team Drives prepend the location with the folder ID like `{id:<folderId>}/...`.<br />Supports [placeholder](placeholder.mdx) substitution. |
-| `password` | `string` | The password to be used PDF decryption. |
+| `password` | `string` | The password to be used for PDF decryption. |
 | `toMimeType` | `string` | Convert to a Google file type using one of the <a href="https://developers.google.com/drive/api/guides/mime-types?hl=en">supported mime-types by Google Drive</a>, like:<br />* `application/vnd.google-apps.document`: Google Docs<br />* `application/vnd.google-apps.presentation`: Google Slides<br />* `application/vnd.google-apps.spreadsheet`: Google Sheets |
 
 ## Global Actions

docs/docs/reference/actions.mdx

@@ -1,43 +1,8 @@
 include "update-docs-extract-common";
 
-{
-    Project: 1, # 0x1
-    Module: 2, # 0x2
-    Namespace: 4, # 0x4
-    Enum: 8, # 0x8
-    EnumMember: 16, # 0x10
-    Variable: 32, # 0x20
-    Function: 64, # 0x40
-    Class: 128, # 0x80
-    Interface: 256, # 0x100
-    Constructor: 512, # 0x200
-    Property: 1024, # 0x400
-    Method: 2048, # 0x800
-    CallSignature: 4096, # 0x1000
-    IndexSignature: 8192, # 0x2000
-    ConstructorSignature: 16384, # 0x4000
-    Parameter: 32768, # 0x8000
-    TypeLiteral: 65536, # 0x10000
-    TypeParameter: 131072, # 0x20000
-    Accessor: 262144, # 0x40000
-    GetSignature: 524288, # 0x80000
-    SetSignature: 1048576, # 0x100000
-    TypeAlias: 2097152, # 0x200000
-    Reference: 4194304, # 0x400000
-} as $kinds
-
-| {
-  GlobalActions: "global",
-  MessageActions: "message",
-  ThreadActions: "thread",
-  AttachmentActions: "attachment"
-} as $typeMap
-
-| [
-  ..
-  | select(type=="object" and .id)
-  | del(.symbolIdMap,.sources,.groups)
- ] as $list
+getKinds as $kinds
+| getTypeMap as $typeMap
+| getDeclarations as $list
 
 # Iterate over action classes:
 | [
@@ -46,7 +11,7 @@ include "update-docs-extract-common";
   | .key as $className
   | .value as $prefix
   | $list[]
-  | select(.kind==$kinds["Class"] and .name==$className)
+  | select(.kind==$kinds["Class"] and .variant=="declaration" and .name==$className)
   | .id as $id
 
   # Get methods, args, properties, types
@@ -64,7 +29,7 @@ include "update-docs-extract-common";
     args: [
       .parameters[]
       | select(.name=="args")
-      | propertiesFromType($list;$kinds)
+      | propertiesFromType($list)
     ]
     | sort_by(.name)
   }

docs/package-lock.json

@@ -1,6 +1,58 @@
+def getTypeMap: (
+  {
+    GlobalActions: "global",
+    MessageActions: "message",
+    ThreadActions: "thread",
+    AttachmentActions: "attachment"
+  }
+);
+
+def getKinds: (
+  {
+    Project: 1, # 0x1
+    Module: 2, # 0x2
+    Namespace: 4, # 0x4
+    Enum: 8, # 0x8
+    EnumMember: 16, # 0x10
+    Variable: 32, # 0x20
+    Function: 64, # 0x40
+    Class: 128, # 0x80
+    Interface: 256, # 0x100
+    Constructor: 512, # 0x200
+    Property: 1024, # 0x400
+    Method: 2048, # 0x800
+    CallSignature: 4096, # 0x1000
+    IndexSignature: 8192, # 0x2000
+    ConstructorSignature: 16384, # 0x4000
+    Parameter: 32768, # 0x8000
+    TypeLiteral: 65536, # 0x10000
+    TypeParameter: 131072, # 0x20000
+    Accessor: 262144, # 0x40000
+    GetSignature: 524288, # 0x80000
+    SetSignature: 1048576, # 0x100000
+    TypeAlias: 2097152, # 0x200000
+    Reference: 4194304, # 0x400000
+  }
+);
+
+def getDeclarations: (
+  [
+    ..
+    | select(type=="object" and .kind>4 and .variant=="declaration" and .id)
+    | del(.symbolIdMap,.sources,.groups)
+  ]
+  | sort_by(.id)
+);
+
+def commentSummaryToDescription: (
+  (.comment?.summary // [])
+  | map(.text)
+  | join("")
+);
+
 def extractDescription: (
   {
-    description: ([.comment?.summary?[]?.text]|join("")),
+    description: commentSummaryToDescription,
     deprecated: ([.comment?.blockTags?[]?|select(.tag=="@deprecated")]|length>0),
     deprecationInfo: ([.comment?.blockTags?[]?|select(.tag=="@deprecated")|.content?[]?.text]|join("")),
   }
@@ -12,46 +64,47 @@ def flattenTypes: (
   | walk(if type=="object" and .children then (.|del(.children)) else . end)
 );
 
-def resolveType($list): (
+def resolveType($declarations): (
   . as $type
-  | $list
+  | $declarations
   | [
     .[] | select(.id == $type.target)
   ] | first
 );
 
-def resolveTypes($list): (
+def resolveTypes($declarations): (
   walk(
     if type=="object" then
       if has("target") and (.target|type)=="number" then
-        . * resolveType($list)
+        . * resolveType($declarations)
         | del(.target)
-      elif has("type") and .type=="intersection" and has("types") then
+      elif has("type") and (.type=="intersection" or .type=="union") and has("types") then
         .types = [
           .types[]
-          | resolveTypes($list)
+          | resolveTypes($declarations)
         ]
       else
-        map_values(resolveTypes($list))
+        map_values(resolveTypes($declarations))
       end
     else 
       .
     end
+    | del(.sources?)
   )
 );
 
-def typeRefName($list;$kinds): (
+def typeRefName($declarations): (
   . as $type
   # | if type == "string" then
   #   .
   | if type == "object" then
     if $type.type == "intrinsic"
       or $type.variant == "declaration"
-      or $type.kind==$kinds.Enum then
+      or $type.kind==getKinds.Enum then
       {name:$type.name}
     elif $type.type == "array" then
       $type.elementType
-      | typeRefName($list;$kinds)
+      | typeRefName($declarations)
       | {
         name: (.name + "[]"),
         ref: .name,
@@ -65,28 +118,29 @@ def typeRefName($list;$kinds): (
         | .name = .name + "<" + ([$type.typeArguments[].name] | join(",")) + ">"
       end
     elif $type.type == "reflection" then
-      debug("typeRefName: reflection \(.)")
       [
         $type.declaration.children[]
-        | .name + ": " + (.type|typeRefName($list;$kinds).name)
+        | .name + ": " + (.type|typeRefName($declarations).name)
       ]
       | join(", ")
       | "{" + . + "}"
       | {name: .}
     elif $type.type == "union" and ($type|has("types")) then
       [
         $type.types[]
-        | typeRefName($list;$kinds).name
+        | typeRefName($declarations).name
       ] | join(" | ")
       | {name: .}
     elif $type.type == "intersection" and ($type|has("types")) then
       [
         $type.types[]
-        | typeRefName($list;$kinds).name
+        | typeRefName($declarations).name
       ] | join(" & ")
       | {name:.}
     elif ($type.type|type)=="object" and $type.type.name then
       {name:$type.type.name}
+    elif .name then
+      .
     else
       error("typeRefName: unexpected else object: \(.)")
     end
@@ -95,31 +149,34 @@ def typeRefName($list;$kinds): (
       ref: (.ref // .name),
     }
   else
-    error("typeRefName: unexpected else type: \($type)")
+    # error("typeRefName: unexpected else type: \($type)")
+    {name:$type}
   end
 );
 
-def extractPropertiesFromType($list;$kinds): (
-  if type=="object" then
-    if .declaration?.children then
-      .declaration?.children?[]?
-      | select(.kind==$kinds["Property"])
-    elif .type=="intersection" then
-      .types[]
-      | extractPropertiesFromType($list;$kinds)
-    elif (.type|type)=="object" then
-      .type
-      | extractPropertiesFromType($list;$kinds)
-    end
+def extractPropTypes($declarations): (
+  resolveTypes($declarations)
+  | if .declaration?.children then
+    .declaration?.children?[]?
+    | select(.kind==getKinds["Property"])
+  elif (.type|type)=="object" then
+    .type
+    | extractPropTypes($declarations)
+  elif .type=="intersection" or .type=="union" then
+    .types[]
+    | extractPropTypes($declarations)
+  elif .type=="reference" and .variant=="declaration" and .children then
+    .children[]
+  else
+    error("extractPropTypes: unexpected else object: \(.)")
   end
 );
 
-def propertiesFromType($list;$kinds): (
-  resolveTypes($list)
-  | extractPropertiesFromType($list;$kinds)
+def propertiesFromType($declarations): (
+  extractPropTypes($declarations)
   | {
     name,
-    type: (.type | typeRefName($list;$kinds)),
-    description: ([.comment?.summary?[]?.text]|join("")),
+    type: (.type | typeRefName($declarations)),
+    description: commentSummaryToDescription,
   }
 );

package-lock.json

@@ -18,6 +18,7 @@ function extractAllDocs() {
   local jsonfile="${1}"
   npx typedoc \
     --json "${jsonfile}" \
+    --sort alphabetical \
     --readme none \
     --exclude 'src/**/generated/**/*.ts' \
     'src/lib/**/*.ts'

scripts/update-docs-extract-actions.jq

@@ -295,9 +295,7 @@ export class GDriveAdapter extends BaseAdapter {
   /**
    * Creates a new file in Google Drive
    * @param location - The location of the file including the filename
-   * @param content - The content of the file as a string representation
-   * @param mimeType - The mime-type of the file
-   * @param description - The description of the file
+   * @param fileData - The content of the file
    * @param conflictStrategy - The conflict strategy in case a file already exists at the file location (skip, replace)
    */
   public createFile(

scripts/update-docs-extract-common.jq

@@ -120,7 +120,7 @@ export class GmailAdapter extends BaseAdapter {
   /**
    * Generate HTML code for one message of a thread.
    * @param thread - The thread to be represented as HTML
-   * @param skipHeader - Whether to skip the header in the generated HTML
+   * @param options - The options for generating the HTML code
    */
   public threadAsHtml(
     thread: GoogleAppsScript.Gmail.GmailThread,

scripts/update-docs.sh

@@ -82,7 +82,7 @@ export type StoreActionBaseArgs = {
 
 export type StoreDecryptedPdfActionArgs = StoreActionBaseArgs & {
   /**
-   * The password to be used PDF decryption.
+   * The password to be used for PDF decryption.
    */
   password: string
 }