docs: support since, deprecated, and feature flag tags in dml reference (#13741)

www/utils/packages/docs-generator/src/classes/kinds/default.ts

@@ -606,14 +606,22 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
     deprecatedTag: ts.JSDocTag | undefined
     sinceTag: ts.JSDocTag | undefined
     featureFlagTag: ts.JSDocTag | undefined
+    summary: string | undefined
   } {
     const nodeComments = ts.getJSDocCommentsAndTags(node)
     let deprecatedTag: ts.JSDocTag | undefined
     let sinceTag: ts.JSDocTag | undefined
     let featureFlagTag: ts.JSDocTag | undefined
+    let summary: string | undefined
 
     nodeComments.forEach((comment) => {
       if (!("tags" in comment)) {
+        if (ts.isJSDoc(comment) && comment.comment) {
+          summary =
+            typeof comment.comment === "string"
+              ? comment.comment
+              : comment.comment.map((part) => part.text).join(" ")
+        }
         return
       }
 
@@ -636,9 +644,22 @@ class DefaultKindGenerator<T extends ts.Node = ts.Node> {
       deprecatedTag,
       sinceTag,
       featureFlagTag,
+      summary,
     }
   }
 
+  formatJSDocTag(tag: ts.JSDocTag | undefined): string | undefined {
+    if (!tag) {
+      return undefined
+    }
+
+    if (typeof tag.comment === "string") {
+      return tag.comment
+    }
+
+    return tag.comment?.map((part) => part.text).join(" ")
+  }
+
   /**
    * Check if a node is ignored.
    *

www/utils/packages/docs-generator/src/classes/kinds/dml.ts

@@ -101,10 +101,24 @@ class DmlKindGenerator extends DefaultKindGenerator<ts.CallExpression> {
           dataModelName,
         })
 
+    /**
+     * Use parent to get tags like since, deprecated, featureFlag
+     */
+    const parent = node.parent?.parent?.parent
+
+    const { sinceTag, deprecatedTag, featureFlagTag } =
+      this.getInformationFromTags(parent)
+
     const dmlFile: DmlFile = {
       [dataModelName]: {
         filePath: getBasePath(node.getSourceFile().fileName),
         properties,
+        since: this.formatJSDocTag(sinceTag),
+        deprecated: {
+          is_deprecated: !!deprecatedTag,
+          description: this.formatJSDocTag(deprecatedTag),
+        },
+        featureFlag: this.formatJSDocTag(featureFlagTag),
       },
     }
 
@@ -229,8 +243,11 @@ class DmlKindGenerator extends DefaultKindGenerator<ts.CallExpression> {
       )
       const isBoolean = propertyTypeStr.includes("BooleanProperty")
       const relationName = isRelation ? camelToWords(propertyName) : undefined
+      const { summary, sinceTag, deprecatedTag, featureFlagTag } =
+        this.getInformationFromTags(propertyNode)
 
       let propertyDescription =
+        summary ||
         this.knowledgeBaseFactory.tryToGetObjectPropertySummary({
           retrieveOptions: {
             str: propertyName,
@@ -251,6 +268,24 @@ class DmlKindGenerator extends DefaultKindGenerator<ts.CallExpression> {
         propertyDescription += `\n\n@expandable`
       }
 
+      if (sinceTag) {
+        propertyDescription += `\n\n@since ${
+          this.formatJSDocTag(sinceTag) ?? ""
+        }`
+      }
+
+      if (featureFlagTag) {
+        propertyDescription += `\n\n@featureFlag ${
+          this.formatJSDocTag(featureFlagTag) ?? ""
+        }`
+      }
+
+      if (deprecatedTag) {
+        propertyDescription += `\n\n@deprecated ${
+          this.formatJSDocTag(deprecatedTag) ?? ""
+        }`
+      }
+
       properties[propertyName] = propertyDescription
     })