fix: Documentation generation enhancements (#227)

* fix: Documentation generation * fix: Update if statement to gen cpp code properly * fix: Update how additionalProperties are generated for markdown * fix: Add deprecation warnings to markdown docs * fix: Alter if/else logic in getSchemaType func * fix: Typo for patternProperties --------- Co-authored-by: kschrief <[email protected]>
rdkcentral · Nov 5, 2024 · 7fe212b · 7fe212b
1 parent fe137d0
commit 7fe212b
Show file tree

Hide file tree

Showing 6 changed files with 46 additions and 22 deletions.
diff --git a/languages/markdown/templates/methods/default.md b/languages/markdown/templates/methods/default.md
@@ -1,5 +1,12 @@
 ### ${method.name}
+${if.deprecated} 
+[Deprecated] This method is deprecated as of ${method.deprecation}. ${if.method.alternative}Please use `${method.alternative}` as a replacement.${end.if.method.alternative}
 
+```typescript
+${method.signature}
+```
+${end.if.deprecated}
+${if.not.deprecated}
 ${method.summary}
 
 ```typescript
@@ -17,5 +24,5 @@ ${method.capabilities}
 #### Examples
 
 ${method.examples}
-
+${end.if.not.deprecated}
 ---
diff --git a/languages/markdown/templates/methods/event.md b/languages/markdown/templates/methods/event.md
@@ -1,5 +1,11 @@
 ### ${event.name}
 
+${if.deprecated}
+[Deprecated] This method is deprecated as of ${method.deprecation}. ${if.method.alternative}Please use `${method.alternative}` as a replacement.${end.if.method.alternative}
+${end.if.deprecated}
+
+${if.not.deprecated}
+
 ```typescript
 function listen('${event.name}', ${event.signature.params}${if.context}, ${end.if.context}(${event.result.type}) => void): Promise<number>
 ```
@@ -16,5 +22,5 @@ ${method.capabilities}
 #### Examples
 
 ${method.examples}
-
+${end.if.not.deprecated}
 ---
diff --git a/languages/markdown/templates/schemas/schemas/index.md b/languages/markdown/templates/schemas/schemas/index.md
@@ -4,12 +4,8 @@ title: ${info.title}
 
 # ${info.title}
 ---
-Version ${info.version}
 
 ## Table of Contents
 ${toc}
 
-## Overview
- ${info.description}
-
 /* ${SCHEMAS} */
diff --git a/languages/markdown/templates/types/additionalProperties.md b/languages/markdown/templates/types/additionalProperties.md
@@ -0,0 +1 @@
+[property: string]: ${type}
diff --git a/src/macrofier/engine.mjs b/src/macrofier/engine.mjs
@@ -930,6 +930,10 @@ function generateSchemas(json, templates, options) {
     else {
       content = content.replace(/\$\{if\.description\}(.*?)\{end\.if\.description\}/gms, '$1')
     }
+
+    // Schema title is requuired for proper documentation generation
+    if (!schema.title) schema.title = name
+
     const schemaShape = types.getSchemaShape(schema, json, { templateDir: state.typeTemplateDir, destination: state.destination, section: options.section, primitive: config.primitives ? Object.keys(config.primitives).length > 0 : false })
 
     content = content
@@ -1521,10 +1525,15 @@ function insertMethodMacros(template, methodObj, json, templates, type = '', exa
 
 
   if (method.deprecated) {
+    if (method.alternative) {
+      template = template.replace(/\$\{if\.method\.alternative\}(.*?)\$\{end\.if\.method\.alternative\}/gms, '$1')
+    }
     template = template.replace(/\$\{if\.deprecated\}(.*?)\$\{end\.if\.deprecated\}/gms, '$1')
+    template = template.replace(/\$\{if\.not\.deprecated\}(.*?)\$\{end\.if\.not\.deprecated\}/gms, '')
   }
   else {
     template = template.replace(/\$\{if\.deprecated\}(.*?)\$\{end\.if\.deprecated\}/gms, '')
+    template = template.replace(/\$\{if\.not\.deprecated\}(.*?)\$\{end\.if\.not\.deprecated\}/gms, '$1')
   }
 
   // method.params[n].xxx macros

diff --git a/src/macrofier/types.mjs b/src/macrofier/types.mjs
@@ -664,6 +664,9 @@ function getSchemaShape(schema = {}, module = {}, { templateDir = 'types', paren
   else if (schema.type) {
     const shape = insertPrimitiveMacros(getTemplate(path.join(templateDir, 'primitive' + suffix)), schema, module, theTitle, templateDir)
     result = result.replace(/\$\{shape\}/g, shape)
+    if (!config.langcode) {
+      return insertSchemaMacros(result, schema, module, { name: theTitle, parent, property, required, templateDir })
+    }
     if (level > 0 || primitive) {
       return insertSchemaMacros(result, schema, module, { name: theTitle, parent, property, required, templateDir })
     }
@@ -877,24 +880,26 @@ function getSchemaType(schema, module, { destination, templateDir = 'types', lin
   else if (schema.type) {
     let template = getTemplate(path.join(templateDir, 'additionalProperties'))
     if (schema.additionalProperties && template ) {
-      return insertSchemaMacros(getTemplate(path.join(templateDir, 'Title')), schema, module, { name: theTitle, recursive: false })
-    }
-    else {
-      template = getTemplate(path.join(templateDir, 'patternProperties'))
-      if (schema.paternProperties && template ) {
-       return insertSchemaMacros(getTemplate(path.join(templateDir, 'Title')), schema, module, { name: theTitle, recursive: false })
-      }
-      else {
-        // TODO: this assumes that when type is an array of types, that it's one other primative & 'null', which isn't necessarily true.
-        const schemaType = !Array.isArray(schema.type) ? schema.type : schema.type.find(t => t !== 'null')
-        const baseDir = (templateDir !== 'json-types' ? 'types': templateDir)
-        let primitive = getPrimitiveType(schemaType, baseDir, schema.title ? true: false)
-        primitive = primitive ? primitive.replace(/\$\{title\}/g, schema.title) : primitive
-        const type = allocatedProxy ? allocatedPrimitiveProxies[schemaType] || primitive : primitive
-
-        return wrap(type, code ? '`' : '')
+      const result = insertSchemaMacros(getTemplate(path.join(templateDir, 'Title')), schema, module, { name: theTitle, recursive: false })
+
+      if (result) {
+        return result
       }
     }
+
+    template = getTemplate(path.join(templateDir, 'patternProperties'))
+    if (schema.patternProperties && template ) {
+      return insertSchemaMacros(getTemplate(path.join(templateDir, 'Title')), schema, module, { name: theTitle, recursive: false })
+    } else {
+      // TODO: this assumes that when type is an array of types, that it's one other primative & 'null', which isn't necessarily true.
+      const schemaType = !Array.isArray(schema.type) ? schema.type : schema.type.find(t => t !== 'null')
+      const baseDir = (templateDir !== 'json-types' ? 'types': templateDir)
+      let primitive = getPrimitiveType(schemaType, baseDir, schema.title ? true: false)
+      primitive = primitive ? primitive.replace(/\$\{title\}/g, schema.title) : primitive
+      const type = allocatedProxy ? allocatedPrimitiveProxies[schemaType] || primitive : primitive
+
+      return wrap(type, code ? '`' : '')
+    }
   }
   else {
     let type