chore: added TSDoc for workflow utility functions (#5674)

* feat(translation): Init plugin * Create migration and entity * Start service implementation * fix typo * typings * config * lang -> locale * chnge config * link * update link * update export * workflow composer (wip) * workflow step/workflow * simplify api * Add structured tests * Add step name onto the step function for future usage * new abstraction level of exported workflow * cleanup * rm step 4 * Add parallelize support to workflow composition * add Symbols and support primitive types as input * rem .only * eslint * cleanup + test * resultFrom * prevent undefined from crashing * finalise tests * chore: transform * chore: tests and transform type * move translation to my dummy * chore: copy before transform * yarn.lock * chore: shortcut to property access * Add type safety * WIP typesafety * WIP * finalise typings * remove extends unknown * WIP * finalise transform typings * finalise transform typings * workflow typs * More typings in invoke and compensate * rm comment * Context as the last args * fix step function type * types * fixes * fixes compose * chore: transform * chore: fix tests and transform Proxy * chore: args length * uncomment * chore: array fill * WIP fix filler * WIP fix filler * chore: remove only * apply gap filler to create step invoke * context first * fixes * wofkrlow ts documentation * wofkrlow ts documentation * wofkrlow ts documentation * wofkrlow ts documentation * wofkrlow ts documentation * chore: hook * hook types * update types * don't loose previous iteration * update implementation * fix some tests part 1 * finalise typings * rm new lines * fixes * wip * fixes * fix tests * simplify types * simplify types * update export * improve types exclusion compensateInput * allow a workflow to return plain object composed of stepReturn properties * only allow one handler for the hook registration * only allow one handler for the hook registration * workflow loading * lint * lint * lint * finalise tests * try to fix ci * try to fix ci * remove corepack step * cleanup * cleanup * cleanup * chore: context as 2nd argumentq * added tsdoc for some workflow functions * Add support for StepResponse and re work the typings * changeset * chore: invoke output as default compensate input * copy data * copy data * fix createWorkflow result * added tsdoc to remaining utility functions * rm test file * proxify input and transformer as well * transformer should re run + type update * rework step response * allow void return from steps * updates to the TSDocs * address comments * address PR feedback * add await for API Route examples * ignore documenting hooks --------- Co-authored-by: adrien2p <adrien.deperetti@gmail.com> Co-authored-by: Carlos R. L. Rodrigues <rodrigolr@gmail.com> Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>
2023-11-23 16:38:43 +00:00
parent 1e39a95f8a
commit f3e20379b0
28 changed files with 687 additions and 175 deletions
@@ -14,6 +14,7 @@ module.exports = {
  ),
  pluginsResolvePath: path.join(pathPrefix, "www"),
  exclude: [path.join(pathPrefix, "node_modules/**")],
+  excludeInternal: true,
  // Uncomment this when debugging
  // showConfig: true,
 }
@@ -17,6 +17,14 @@
    {
      "tagName": "@apiIgnore",
      "syntaxKind": "modifier"
+    },
+    {
+      "tagName": "@mainSignature",
+      "syntaxKind": "modifier"
+    },
+    {
+      "tagName": "@docHideSignature",
+      "syntaxKind": "modifier"
    }
  ]
 }
@@ -0,0 +1,6 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "extends": [
+    "../../../../packages/workflows/tsconfig.json"
+  ]
+}
@@ -0,0 +1,75 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+const path = require("path")
+const globalTypedocOptions = require("./_base")
+
+const pathPrefix = path.join(__dirname, "..", "..", "..")
+
+module.exports = {
+  ...globalTypedocOptions,
+  entryPoints: [
+    path.join(pathPrefix, "packages/workflows/src/utils/composer/index.ts"),
+  ],
+  out: [path.join(pathPrefix, "www/apps/docs/content/references/workflows")],
+  tsconfig: path.join(__dirname, "extended-tsconfig", "workflows.json"),
+  name: "Workflows Reference",
+  indexTitle: "Workflows Reference",
+  entryDocument: "index.mdx",
+  hideInPageTOC: true,
+  hideBreadcrumbs: true,
+  formatting: {
+    "*": {
+      expandMembers: true,
+      showCommentsAsHeader: true,
+      sections: {
+        member_sources_definedIn: false,
+        reflection_hierarchy: false,
+        member_sources_inheritedFrom: false,
+        member_sources_implementationOf: false,
+        reflection_implementedBy: false,
+        member_signature_sources: false,
+        reflection_callable: false,
+        reflection_indexable: false,
+        member_signature_title: false,
+        member_signature_returns: false,
+        member_getterSetter: false,
+      },
+      parameterStyle: "component",
+      parameterComponent: "ParameterTypes",
+      mdxImports: [
+        `import ParameterTypes from "@site/src/components/ParameterTypes"`,
+      ],
+      frontmatterData: {
+        displayed_sidebar: "workflowsSidebar",
+      },
+    },
+    "index\\.mdx": {
+      reflectionGroups: {
+        Namespaces: false,
+        Enumerations: false,
+        Classes: false,
+        Interfaces: false,
+        "Type Aliases": false,
+        Variables: false,
+        "Enumeration Members": false,
+      },
+    },
+    functions: {
+      maxLevel: 1,
+    },
+    "classes/StepResponse": {
+      reflectionGroups: {
+        Properties: false,
+      },
+    },
+    transform: {
+      reflectionGroups: {
+        "Type Parameters": false,
+      },
+    },
+  },
+  objectLiteralTypeDeclarationStyle: "component",
+  mdxOutput: true,
+  maxLevel: 2,
+  allReflectionsHaveOwnDocument: true,
+  excludeExternals: true,
+}
@@ -4,6 +4,7 @@ import { load as frontmatterPlugin } from "./frontmatter-plugin"
 import { load as parseOasSchemaPlugin } from "./parse-oas-schema-plugin"
 import { load as apiIgnorePlugin } from "./api-ignore"
 import { load as eslintExamplePlugin } from "./eslint-example"
+import { load as signatureModifierPlugin } from "./signature-modifier"

 export function load(app: Application) {
  resolveReferencesPluginLoad(app)
@@ -11,4 +12,5 @@ export function load(app: Application) {
  parseOasSchemaPlugin(app)
  apiIgnorePlugin(app)
  eslintExamplePlugin(app)
+  signatureModifierPlugin(app)
 }
@@ -0,0 +1,21 @@
+import {
+  Application,
+  Context,
+  Converter,
+  ProjectReflection,
+  SignatureReflection,
+} from "typedoc"
+
+export function load(app: Application) {
+  app.converter.on(
+    Converter.EVENT_CREATE_SIGNATURE,
+    (
+      context: Context,
+      signature: SignatureReflection | ProjectReflection | undefined
+    ) => {
+      if (signature?.comment?.hasModifier("@hideSignature")) {
+        context.project.removeReflection(signature)
+      }
+    }
+  )
+}
@@ -31,13 +31,13 @@ function getReturnFromType(
    return ""
  }

-  const componentItems = returnReflectionComponentFormatter(
-    reflection.type,
-    reflection.project || theme.project,
-    reflection.comment,
-    1,
-    maxLevel
-  )
+  const componentItems = returnReflectionComponentFormatter({
+    reflectionType: reflection.type,
+    project: reflection.project || theme.project,
+    comment: reflection.comment,
+    level: 1,
+    maxLevel,
+  })

  if (parameterStyle === "component") {
    return `<${parameterComponent} parameters={${JSON.stringify(
@@ -15,7 +15,7 @@ export default function (theme: MarkdownTheme) {
        theme.getFormattingOptionsForLocation()
      if (sections && sections.member_signature_title === false) {
        // only show title if there are more than one signatures
-        if (!this.parent.signatures || this.parent.signatures?.length <= 1) {
+        if (!this.parent.signatures || this.parent.signatures.length <= 1) {
          return ""
        }
      }
@@ -12,7 +12,7 @@

 {{#if (sectionEnabled "member_declaration_example")}}

-{{{example this 3}}}
+{{{example this 4}}}

 {{/if}}

@@ -20,7 +20,7 @@

 {{#if typeParameters}}

-{{titleLevel 3}} Type parameters
+{{{titleLevel 4}}} Type Parameters

 {{#with typeParameters}}

@@ -40,7 +40,7 @@

 {{#with type.declaration.indexSignature}}

-{{titleLevel 3}} Index signature
+{{titleLevel 4}} Index signature

 {{{indexSignatureTitle}}}

@@ -58,17 +58,17 @@

 {{#if type.declaration.children}}

-{{titleLevel 3}} Call signature
+{{{titleLevel 4}}} Call signature

 {{else}}

-{{titleLevel 3}} Type declaration
+{{{titleLevel 4}}} Type declaration

 {{/if}}

 {{#each type.declaration.signatures}}

-{{> member.signature showSources=false }}
+{{> member.signature showSources=false commentLevel=5 }}

 {{/each}}

@@ -82,7 +82,7 @@

 {{#with type.declaration}}

-{{titleLevel 3}} Type declaration
+{{{titleLevel 4}}} Type declaration

 {{/with}}

@@ -4,7 +4,7 @@

 {{#with getSignature}}

-{{> member.signature accessor="get" showSources=true }}
+{{> member.signature accessor="get" showSources=true commentLevel=4 }}

 {{/with}}

@@ -18,7 +18,7 @@

 {{#with setSignature}}

-{{> member.signature accessor="set" showSources=true }}
+{{> member.signature accessor="set" showSources=true commentLevel=4 }}

 {{/with}}

@@ -2,7 +2,7 @@

 {{#if name}}

-{{titleLevel 3}} {{#ifNamedAnchors}}<a id="{{anchor}}" name="{{this.anchor}}"></a> {{/ifNamedAnchors}}{{ escape name }}
+{{titleLevel 4}} {{#ifNamedAnchors}}<a id="{{anchor}}" name="{{this.anchor}}"></a> {{/ifNamedAnchors}}{{ escape name }}

 {{/if}}

@@ -14,7 +14,7 @@

 {{#each signatures}}

-{{> member.signature showSources=true }}
+{{> member.signature showSources=true commentLevel=../commentLevel }}

 {{/each}}

@@ -14,10 +14,18 @@

 {{/if}}

+{{#if (sectionEnabled "member_signature_example")}}
+
+{{{example this commentLevel}}}
+
+{{/if}}
+
 {{#if (sectionEnabled "member_signature_typeParameters")}}

 {{#if typeParameters}}

+{{{titleLevel commentLevel}}} Type Parameters
+
 {{#with typeParameters}}

 {{{typeParameter}}}
@@ -28,25 +36,11 @@

 {{/if}}

-{{#if (sectionEnabled "member_signature_example")}}
-
-{{{example this 4}}}
-
-{{/if}}
-
 {{#if (sectionEnabled "member_signature_parameters")}}

 {{#if parameters}}

-{{#if showSources}}
-
-{{{titleLevel 4}}} Parameters
-
-{{else}}
-
-{{{titleLevel 5}}} Parameters
-
-{{/if}}
+{{{titleLevel commentLevel}}} Parameters

 {{#with parameters}}

@@ -62,15 +56,7 @@

 {{#if type}}

-{{#if showSources}}
-
-{{{titleLevel 4}}} Returns
-
-{{else}}
-
-{{{titleLevel 5}}} Returns
-
-{{/if}}
+{{{titleLevel commentLevel}}} Returns

 {{#if (sectionEnabled "member_signature_returns")}}

@@ -92,7 +78,7 @@

 {{#each declaration.signatures}}

-{{> member.signature showSources=false }}
+{{> member.signature showSources=false commentLevel=commentLevel }}

 {{/each}}

@@ -126,7 +112,7 @@

 {{#if hasVisibleComponent}}

-{{{comments this false true 4 ..}}}
+{{{comments this false true commentLevel ..}}}

 {{/if}}

@@ -26,7 +26,7 @@ ___

 {{#each children}}

-{{> member}}
+{{> member commentLevel=5}}

 {{/each}}

@@ -54,7 +54,7 @@ ___

 {{#each children}}

-{{> member}}
+{{> member commentLevel=5}}

 {{/each}}

@@ -16,7 +16,7 @@

 {{#unless hasOwnDocument}}

-{{> member}}
+{{> member commentLevel=4}}

 {{/unless}}

@@ -0,0 +1,9 @@
+{{#if showSources}}
+
+{{{titleLevel 4}}} {{{title}}}
+
+{{else}}
+
+{{{titleLevel 5}}} {{{title}}}
+
+{{/if}}
@@ -94,7 +94,7 @@

 ### {{name}}

-{{> member.signature showSources=true }}
+{{> member.signature showSources=true commentLevel=4 }}

 {{/each}}

@@ -4,6 +4,6 @@

 {{#with model}}

-{{> member}}
+{{> member showSources=false commentLevel=4}}

 {{/with}}
@@ -5,7 +5,6 @@ import {
  PageEvent,
  ProjectReflection,
  Reflection,
-  ReflectionGroup,
  ReflectionKind,
  RenderTemplate,
  Renderer,
@@ -359,22 +358,45 @@ export class MarkdownTheme extends Theme {
    this.location = page.url
    this.reflection =
      page.model instanceof DeclarationReflection ? page.model : undefined
-    const options = this.getFormattingOptionsForLocation()
-    if (this.reflection && this.reflection.groups) {
-      // filter out unwanted groups
-      const tempGroups: ReflectionGroup[] = []
-      this.reflection.groups.forEach((reflectionGroup) => {
-        if (
-          !options.reflectionGroups ||
-          !(reflectionGroup.title in options.reflectionGroups) ||
-          options.reflectionGroups[reflectionGroup.title]
-        ) {
-          tempGroups.push(reflectionGroup)
-        }
-      })

-      this.reflection.groups = tempGroups
+    if (
+      page.model instanceof DeclarationReflection ||
+      page.model instanceof ProjectReflection
+    ) {
+      this.removeGroups(page.model)
    }
+
+    if (
+      this.reflection instanceof DeclarationReflection &&
+      this.reflection.signatures
+    ) {
+      // check if any of its signature has the `@mainSignature` tag
+      // and if so remove other signatures
+      const mainSignatureIndex = this.reflection.signatures.findIndex(
+        (signature) => signature.comment?.hasModifier("@mainSignature")
+      )
+
+      if (mainSignatureIndex !== -1) {
+        const mainSignature = this.reflection.signatures[mainSignatureIndex]
+        this.reflection.signatures = [mainSignature]
+      }
+    }
+  }
+
+  protected removeGroups(model?: DeclarationReflection | ProjectReflection) {
+    if (!model?.groups) {
+      return
+    }
+
+    const options = this.getFormattingOptionsForLocation()
+
+    model.groups = model.groups.filter((reflectionGroup) => {
+      return (
+        !options.reflectionGroups ||
+        !(reflectionGroup.title in options.reflectionGroups) ||
+        options.reflectionGroups[reflectionGroup.title]
+      )
+    })
  }

  get globalsFile() {
@@ -4,6 +4,7 @@ import {
  ProjectReflection,
  ReflectionFlags,
  SomeType,
+  TypeParameterReflection,
 } from "typedoc"
 import * as Handlebars from "handlebars"
 import getType from "./type-utils"
@@ -14,19 +15,27 @@ import {
 } from "./reflection-formatter"
 import { MarkdownTheme } from "../theme"

-export function returnReflectionComponentFormatter(
-  reflectionType: SomeType,
-  project: ProjectReflection,
-  comment?: Comment,
-  level = 1,
+type ReturnReflectionComponentFormatterParams = {
+  reflectionType: SomeType
+  project: ProjectReflection
+  comment?: Comment
+  level: number
  maxLevel?: number | undefined
-): Parameter[] {
+}
+
+export function returnReflectionComponentFormatter({
+  reflectionType,
+  project,
+  comment,
+  level = 1,
+  maxLevel,
+}: ReturnReflectionComponentFormatterParams): Parameter[] {
  const typeName = getType(reflectionType, "object", false, true)
  const type = getType(reflectionType, "object")
  const componentItem: Parameter[] = []
+  const canRetrieveChildren = level + 1 <= (maxLevel || MarkdownTheme.MAX_LEVEL)
  if (reflectionType.type === "reference") {
-    // put type name as a title and its referenced items as children.
-    if (reflectionType.typeArguments) {
+    if (reflectionType.typeArguments || reflectionType.refersToTypeParameter) {
      const parentKey = componentItem.push({
        name: "name" in reflectionType ? reflectionType.name : typeName,
        type,
@@ -45,21 +54,30 @@ export function returnReflectionComponentFormatter(
        featureFlag: Handlebars.helpers.featureFlag(comment),
        children: [],
      })
+      const typeArgs = reflectionType.typeArguments
+        ? reflectionType.typeArguments
+        : "typeParameters" in reflectionType
+        ? (reflectionType.typeParameters as TypeParameterReflection[])
+        : undefined
      if (
-        !isOnlyVoid(reflectionType.typeArguments) &&
-        level + 1 <= (maxLevel || MarkdownTheme.MAX_LEVEL)
+        typeArgs &&
+        !isOnlyVoid(typeArgs as unknown as SomeType[]) &&
+        canRetrieveChildren
      ) {
-        reflectionType.typeArguments.forEach((typeArg) => {
-          const typeArgComponent = returnReflectionComponentFormatter(
-            typeArg,
-            project,
-            undefined,
-            level + 1,
-            maxLevel
-          )
-          if (typeArgComponent.length) {
-            componentItem[parentKey - 1].children?.push(...typeArgComponent)
+        typeArgs.forEach((typeArg) => {
+          const reflectionTypeArg =
+            typeArg instanceof TypeParameterReflection ? typeArg.type : typeArg
+          if (!reflectionTypeArg) {
+            return
          }
+          const typeArgComponent = returnReflectionComponentFormatter({
+            reflectionType: reflectionTypeArg,
+            project,
+            level: level + 1,
+            maxLevel,
+          })
+
+          componentItem[parentKey - 1].children?.push(...typeArgComponent)
        })
      }
    } else {
@@ -107,17 +125,14 @@ export function returnReflectionComponentFormatter(
      featureFlag: Handlebars.helpers.featureFlag(comment),
      children: [],
    })
-    if (level + 1 <= (maxLevel || MarkdownTheme.MAX_LEVEL)) {
-      const elementTypeItem = returnReflectionComponentFormatter(
-        reflectionType.elementType,
+    if (canRetrieveChildren) {
+      const elementTypeItem = returnReflectionComponentFormatter({
+        reflectionType: reflectionType.elementType,
        project,
-        undefined,
-        level + 1,
-        maxLevel
-      )
-      if (elementTypeItem.length) {
-        componentItem[parentKey - 1].children?.push(...elementTypeItem)
-      }
+        level: level + 1,
+        maxLevel,
+      })
+      componentItem[parentKey - 1].children?.push(...elementTypeItem)
    }
  } else if (reflectionType.type === "tuple") {
    let pushTo: Parameter[] = []
@@ -145,18 +160,15 @@ export function returnReflectionComponentFormatter(
    } else {
      pushTo = componentItem
    }
-    if (level + 1 <= (maxLevel || MarkdownTheme.MAX_LEVEL)) {
+    if (canRetrieveChildren) {
      reflectionType.elements.forEach((element) => {
-        const elementTypeItem = returnReflectionComponentFormatter(
-          element,
+        const elementTypeItem = returnReflectionComponentFormatter({
+          reflectionType: element,
          project,
-          undefined,
-          level + 1,
-          maxLevel
-        )
-        if (elementTypeItem.length) {
-          pushTo.push(...elementTypeItem)
-        }
+          level: level + 1,
+          maxLevel,
+        })
+        pushTo.push(...elementTypeItem)
      })
    }
  } else {
@@ -65,7 +65,15 @@ export function getTypeChildren(
      children = getTypeChildren(reflectionType.elementType, project)
  }

-  return children
+  return filterChildren(children)
+}
+
+const REJECTED_CHILDREN_NAMES = ["__type"]
+
+function filterChildren(children: DeclarationReflection[]) {
+  return children.filter(
+    (child) => !REJECTED_CHILDREN_NAMES.includes(child.name)
+  )
 }

 function removeChild(name: unknown, children: DeclarationReflection[]) {