feat: Add PHPDoc to SDK (#456)

Author: razor-x

codegen/layouts/partials/route-method.hbs

@@ -1,3 +1,4 @@
+{{{methodPhpDoc this}}}
     public function {{methodName}}({{{signatureParams}}}): {{returnType}} {
 {{#if hasParams}}
         $request_payload = [];

codegen/layouts/resource.hbs

@@ -3,6 +3,9 @@
 namespace Seam\Resources;
 
 {{#each classes}}
+{{#if (hasPhpDoc this)}}
+{{{resourcePhpDoc this}}}
+{{/if}}
 class {{className}}
 {
     public static function from_json(mixed $json): {{className}}|null
@@ -19,7 +22,10 @@ class {{className}}
 
     public function __construct(
 {{#each constructorParams}}
-        {{{this}}}
+{{#if (hasPhpDoc this)}}
+{{{propertyPhpDoc this}}}
+{{/if}}
+        {{{declaration}}}
 {{/each}}
     ) {
     }

codegen/lib/class-model.ts

@@ -4,13 +4,18 @@
 export interface PhpClientMethodParameter {
   name: string
   type: string
+  description: string
   required?: boolean | undefined
   position?: number | undefined
 }
 
 export interface PhpClientMethod {
   methodName: string
   path: string
+  description: string
+  responseDescription: string
+  isDeprecated: boolean
+  deprecationMessage: string
   parameters: PhpClientMethodParameter[]
   returnResource: string
   returnPath: string

codegen/lib/handlebars-helpers.ts

@@ -1 +1,72 @@
 export const identity = (x: unknown): unknown => x
+
+export interface DeprecatedPhpDocContext {
+  description: string
+  isDeprecated: boolean
+  deprecationMessage: string
+}
+
+export interface MethodPhpDocContext extends DeprecatedPhpDocContext {
+  returnType: string
+  responseDescription: string
+  parameters: Array<{ name: string; type: string; description: string }>
+}
+
+export const resourcePhpDoc = (context: DeprecatedPhpDocContext): string =>
+  createPhpDoc(context.description, deprecatedTag(context))
+
+export const hasPhpDoc = (context: DeprecatedPhpDocContext): boolean =>
+  context.description.trim() !== '' || context.isDeprecated
+
+export const propertyPhpDoc = (context: DeprecatedPhpDocContext): string =>
+  createPhpDoc(context.description, deprecatedTag(context), '        ')
+
+export const methodPhpDoc = (context: MethodPhpDocContext): string =>
+  createPhpDoc(
+    context.description,
+    [
+      ...context.parameters.map(
+        (parameter) =>
+          `@param ${parameter.type} $${parameter.name}${parameter.description === '' ? '' : ` ${parameter.description}`}`,
+      ),
+      `@return ${context.returnType}${context.responseDescription === '' ? '' : ` ${context.responseDescription}`}`,
+      ...deprecatedTag(context),
+    ],
+    '    ',
+  )
+
+const deprecatedTag = (context: DeprecatedPhpDocContext): string[] =>
+  context.isDeprecated
+    ? [
+        `@deprecated${context.deprecationMessage === '' ? '' : ` ${context.deprecationMessage}`}`,
+      ]
+    : []
+
+const createPhpDoc = (
+  description: string,
+  tags: string[],
+  indentation = '',
+): string => {
+  const descriptionLines = description
+    .trim()
+    .split(/\r?\n/)
+    .map(sanitizePhpDocLine)
+  const populatedDescription = description.trim() === '' ? [] : descriptionLines
+  const populatedTags = tags.filter((tag) => tag.trim() !== '').map(sanitizePhpDocLine)
+  const lines = [
+    ...populatedDescription,
+    ...(populatedDescription.length > 0 && populatedTags.length > 0 ? [''] : []),
+    ...populatedTags,
+  ]
+
+  if (lines.length === 0) return ''
+
+  return [
+    `${indentation}/**`,
+    ...lines.map((line) => `${indentation} *${line === '' ? '' : ` ${line}`}`),
+    `${indentation} */`,
+  ].join('\n')
+}
+
+const sanitizePhpDocLine = (line: string): string =>
+  line.replaceAll('*/', '* /').trimEnd()

codegen/lib/layouts/resource.ts

@@ -15,8 +15,18 @@ import type {
 
 export interface ClassLayoutContext {
   className: string
+  description: string
+  isDeprecated: boolean
+  deprecationMessage: string
   fromJsonProps: string[]
-  constructorParams: string[]
+  constructorParams: ConstructorParamLayoutContext[]
+}
+
+export interface ConstructorParamLayoutContext {
+  declaration: string
+  description: string
+  isDeprecated: boolean
+  deprecationMessage: string
 }
 
 export interface ResourceLayoutContext {
@@ -38,20 +48,33 @@ const generateFromJsonProp = (property: ResourceClassProperty): string => {
   }
 }
 
-const generateConstructorParam = (property: ResourceClassProperty): string => {
+const generateConstructorParam = (
+  property: ResourceClassProperty,
+): ConstructorParamLayoutContext => {
+  let declaration: string
   switch (property.kind) {
     case 'objectReference':
-      return `public ${property.referenceName}|null $${property.name},`
+      declaration = `public ${property.referenceName}|null $${property.name},`
+      break
 
     case 'listReference':
-      return `public array $${property.name},`
+      declaration = `public array $${property.name},`
+      break
 
     case 'value': {
       const { phpType } = property
       const nullSuffix = phpType === 'mixed' ? '' : '|null'
-      return `public ${phpType}${nullSuffix} $${property.name},`
+      declaration = `public ${phpType}${nullSuffix} $${property.name},`
+      break
     }
   }
+
+  return {
+    declaration,
+    description: property.description,
+    isDeprecated: property.isDeprecated,
+    deprecationMessage: property.deprecationMessage,
+  }
 }
 
 const getClassLayoutContext = (
@@ -63,6 +86,9 @@ const getClassLayoutContext = (
 
   return {
     className: schema.name,
+    description: schema.description,
+    isDeprecated: schema.isDeprecated,
+    deprecationMessage: schema.deprecationMessage,
     fromJsonProps: sorted.map(generateFromJsonProp),
     constructorParams: sorted.map(generateConstructorParam),
   }

codegen/lib/layouts/seam-client.ts

@@ -10,6 +10,11 @@ import {
 
 export interface MethodLayoutContext {
   methodName: string
+  description: string
+  responseDescription: string
+  isDeprecated: boolean
+  deprecationMessage: string
+  parameters: Array<{ name: string; type: string; description: string }>
   path: string
   returnType: string
   hasParams: boolean
@@ -67,6 +72,15 @@ const getMethodLayoutContext = (
 
   return {
     methodName,
+    description: method.description,
+    responseDescription: method.responseDescription,
+    isDeprecated: method.isDeprecated,
+    deprecationMessage: method.deprecationMessage,
+    parameters: sortedParameters.map(({ name, type, description }) => ({
+      name,
+      type,
+      description,
+    })),
     path,
     returnType,
     hasParams: parameters.length > 0,

codegen/lib/resource-model.ts

@@ -15,12 +15,22 @@ import { pascalCase } from 'change-case'
 import { getPhpType } from './map-php-type.js'
 
 export type ResourceClassProperty =
-  | { name: string; kind: 'value'; phpType: string }
-  | { name: string; kind: 'objectReference'; referenceName: string }
-  | { name: string; kind: 'listReference'; referenceName: string }
+  | ({ kind: 'value'; phpType: string } & ResourceClassPropertyMetadata)
+  | ({ kind: 'objectReference'; referenceName: string } & ResourceClassPropertyMetadata)
+  | ({ kind: 'listReference'; referenceName: string } & ResourceClassPropertyMetadata)
+
+interface ResourceClassPropertyMetadata {
+  name: string
+  description: string
+  isDeprecated: boolean
+  deprecationMessage: string
+}
 
 export interface ResourceClassSchema {
   name: string
+  description: string
+  isDeprecated: boolean
+  deprecationMessage: string
   properties: ResourceClassProperty[]
 }
 
@@ -72,9 +82,18 @@ export const createResourceModel = (blueprint: Blueprint): ResourceModel => {
     name: string,
     properties: Property[],
     baseName: string,
+    description = '',
+    isDeprecated = false,
+    deprecationMessage = '',
   ): void => {
     if (classes.has(name)) return
-    const schema: ResourceClassSchema = { name, properties: [] }
+    const schema: ResourceClassSchema = {
+      name,
+      description,
+      isDeprecated,
+      deprecationMessage,
+      properties: [],
+    }
     classes.set(name, schema)
     if (name !== currentResourceName) {
       localClassNames.get(currentResourceName)?.push(name)
@@ -89,7 +108,17 @@ export const createResourceModel = (blueprint: Blueprint): ResourceModel => {
     const name = pascalCase(resourceType)
     currentResourceName = name
     localClassNames.set(name, [])
-    addClass(name, baseResources.get(resourceType) ?? [], resourceType)
+    const sourceResource =
+      blueprint.resources.find((resource) => resource.resourceType === resourceType) ??
+      (resourceType === 'event' ? blueprint.events[0] : blueprint.actionAttempts[0])
+    addClass(
+      name,
+      baseResources.get(resourceType) ?? [],
+      resourceType,
+      sourceResource?.description,
+      sourceResource?.isDeprecated,
+      sourceResource?.deprecationMessage,
+    )
 
     const resourceClass = classes.get(name)
     if (resourceClass == null) {
@@ -122,16 +151,29 @@ export const createResourceModel = (blueprint: Blueprint): ResourceModel => {
 const createResourceClassProperty = (
   property: Property,
   baseName: string,
-  addClass: (name: string, properties: Property[], baseName: string) => void,
+  addClass: (
+    name: string,
+    properties: Property[],
+    baseName: string,
+    description?: string,
+    isDeprecated?: boolean,
+    deprecationMessage?: string,
+  ) => void,
 ): ResourceClassProperty => {
   const referenceName = pascalCase(`${baseName}_${property.name}`)
+  const metadata = {
+    name: property.name,
+    description: property.description,
+    isDeprecated: property.isDeprecated,
+    deprecationMessage: property.deprecationMessage,
+  }
 
   if (property.format === 'object') {
     const { properties } = property
 
     if (properties.length > 0) {
-      addClass(referenceName, properties, baseName)
-      return { name: property.name, kind: 'objectReference', referenceName }
+      addClass(referenceName, properties, baseName, property.description)
+      return { ...metadata, kind: 'objectReference', referenceName }
     }
   }
 
@@ -146,13 +188,13 @@ const createResourceClassProperty = (
           : []
 
     if (itemProperties.length > 0) {
-      addClass(referenceName, itemProperties, baseName)
-      return { name: property.name, kind: 'listReference', referenceName }
+      addClass(referenceName, itemProperties, baseName, property.description)
+      return { ...metadata, kind: 'listReference', referenceName }
     }
   }
 
   return {
-    name: property.name,
+    ...metadata,
     kind: 'value',
     phpType: getPhpType(property),
   }

codegen/lib/routes.ts

@@ -110,9 +110,14 @@ const createClientMethod = (endpoint: Endpoint): PhpClientMethod => {
   return {
     methodName: endpoint.name,
     path: endpoint.path,
+    description: endpoint.description,
+    responseDescription: response.description,
+    isDeprecated: endpoint.isDeprecated,
+    deprecationMessage: endpoint.deprecationMessage,
     parameters: endpoint.request.parameters.map((parameter) => ({
         name: parameter.name,
         type: getPhpType(parameter),
+        description: parameter.description,
         required: parameter.isRequired,
         // The primary identifier of a get endpoint always sorts first in the
         // method signature.