#320 Define types and interfaces in docs

api-generator/api-generator.js

@@ -46,6 +46,7 @@ async function main() {
 
   if (project) {
     let doc = {};
+    let typesMap = {};
 
     const parseText = (text) => {
       return text.replace(/{/g, '{').replace(/}/g, '}');
@@ -350,47 +351,15 @@ async function main() {
               doc[name]['templates'] = templates;
             }
 
-            if (isProcessable(module_interface_group)) {
-              const interfaces = {
-                description: staticMessages['interfaces'],
-                values: []
-              };
-
-              module_interface_group.children.forEach((int) => {
-                interfaces.values.push({
-                  name: int.name,
-                  description:
-                    int.comment &&
-                    int.comment.summary.map((s) => s.text || '').join(' '),
-                  props:
-                    int.children &&
-                    int.children.map((child) => ({
-                      name: child.name,
-                      optional: child.flags.isOptional,
-                      readonly: child.flags.isReadonly,
-                      type: child.type
-                        ? child.type.toString()
-                        : extractParameter(int),
-                      description:
-                        child.comment &&
-                        child.comment.summary
-                          .map((s) => s.text || '')
-                          .join(' '),
-                      deprecated: getDeprecatedText(child)
-                    }))
-                });
-              });
-
-              doc[name]['interfaces'] = interfaces;
-            }
-
             if (isProcessable(module_service_group)) {
               doc[name] = {
+                ...doc[name]
                 // description: staticMessages['service']
               };
 
               module_service_group.children.forEach((service) => {
                 doc[name] = {
+                  ...doc[name],
                   name: service.name,
                   description: service.comment &&
                     service.comment.summary
@@ -435,6 +404,55 @@ async function main() {
               });
             }
 
+            if (isProcessable(module_interface_group)) {
+              const interfaces = {
+                description: staticMessages['interfaces'],
+                values: []
+              };
+
+              module_interface_group.children.forEach((int) => {
+                interfaces.values.push({
+                  name: int.name,
+                  description:
+                    int.comment &&
+                    int.comment.summary.map((s) => s.text || '').join(' '),
+                  props:
+                    int.children &&
+                    int.children.map((child) => ({
+                      name: child.name,
+                      optional: child.flags.isOptional,
+                      readonly: child.flags.isReadonly,
+                      type: child.type
+                        ? child.type.toString()
+                        : extractParameter(int),
+                      description:
+                        child.comment &&
+                        child.comment.summary
+                          .map((s) => s.text || '')
+                          .join(' '),
+                      deprecated: getDeprecatedText(child)
+                    }))
+                });
+                typesMap[int.name] = int.comment.blockTags?.find(
+                  tag => tag.tag === "@customPath"
+                )?.content?.map((s) => s.text || '').join(' ')
+                  ?? name.replace("cps-", "");
+              });
+
+              if (doc[name]?.interfaces) {
+                doc[name]['interfaces'] = {
+                  ...doc[name]['interfaces'],
+                  values: [
+                    ...doc[name]['interfaces'].values,
+                    ...interfaces.values
+                  ]
+                };
+              } else {
+                doc[name]['interfaces'] = interfaces;
+              }
+            }
+
+
             if (isProcessable(module_types_group)) {
               const types = {
                 description: staticMessages['types'],
@@ -449,9 +467,23 @@ async function main() {
                     t.comment.summary &&
                     t.comment.summary.map((s) => s.text || '').join(' ')
                 });
+                typesMap[t.name] = t.comment.blockTags?.find(
+                  tag => tag.tag === "@customPath"
+                )?.content?.map((s) => s.text || '').join(' ')
+                  ?? name.replace("cps-", "");
               });
 
-              doc[name]['types'] = types;
+              if (doc[name]?.types) {
+                doc[name]['types'] = {
+                  ...doc[name]['types'],
+                  values: [
+                    ...doc[name]['types'].values,
+                    ...types.values
+                  ]
+                };
+              } else {
+                doc[name]['types'] = types;
+              }
             }
           }
         }
@@ -488,6 +520,12 @@ async function main() {
       fs.writeFileSync(path.resolve(outputPath, `${key}.json`), typedocJSON);
     }
 
+    if (Object.entries(typesMap).length) {
+      const typesMapJSON = JSON.stringify(typesMap, null, 4);
+      !fs.existsSync(outputPath) && fs.mkdirSync(outputPath);
+      fs.writeFileSync(path.resolve(outputPath, `types_map.json`), typesMapJSON);
+    }
+
     // const typedocJSON = JSON.stringify(mergedDocs, null, 4);
     // !fs.existsSync(outputPath) && fs.mkdirSync(outputPath);
     // fs.writeFileSync(path.resolve(outputPath, 'index.json'), typedocJSON);
@@ -557,6 +595,8 @@ const getTypesValue = (typeobj) => {
 
       return JSON.stringify(Object.assign({}, ...values), null, 4);
     }
+    // TODO: Handle "typeof iconNames[number] properly
+    return type.toString();
   }
 };
 

projects/composition/src/app/api-data/cps-autocomplete.json

@@ -345,5 +345,15 @@
                 ]
             }
         }
+    },
+    "types": {
+        "description": "Defines the custom types used by the module.",
+        "values": [
+            {
+                "name": "CpsAutocompleteAppearanceType",
+                "value": "\"outlined\" | \"underlined\" | \"borderless\"",
+                "description": "CpsAutocompleteAppearanceType is used to define the border of the autocomplete input."
+            }
+        ]
     }
 }

projects/composition/src/app/api-data/cps-button-toggle.json

@@ -127,5 +127,15 @@
                 ]
             }
         }
+    },
+    "types": {
+        "description": "Defines the custom types used by the module.",
+        "values": [
+            {
+                "name": "CpsButtonToggleOption",
+                "value": "{\n    \"value\": \"any\",\n    \"label\": \"string\",\n    \"icon\": \"string\",\n    \"disabled\": \"boolean\",\n    \"tooltip\": \"string\"\n}",
+                "description": "CpsButtonToggleOption is used to define the options of the CpsButtonToggleComponent."
+            }
+        ]
     }
 }

projects/composition/src/app/api-data/cps-datepicker.json

@@ -172,5 +172,15 @@
                 ]
             }
         }
+    },
+    "types": {
+        "description": "Defines the custom types used by the module.",
+        "values": [
+            {
+                "name": "CpsDatepickerAppearanceType",
+                "value": "\"outlined\" | \"underlined\" | \"borderless\"",
+                "description": "CpsDatepickerAppearanceType is used to define the border of the datepicker input."
+            }
+        ]
     }
 }

projects/composition/src/app/api-data/cps-dialog.json

@@ -1,4 +1,5 @@
 {
+    "components": {},
     "name": "CpsDialogService",
     "description": "Service for showing CpsDialog.",
     "methods": {

projects/composition/src/app/api-data/cps-icon.json

@@ -32,5 +32,20 @@
                 ]
             }
         }
+    },
+    "types": {
+        "description": "Defines the custom types used by the module.",
+        "values": [
+            {
+                "name": "IconType",
+                "value": "typeof iconNames[number]",
+                "description": "IconType is used to define the type of the icon."
+            },
+            {
+                "name": "iconSizeType",
+                "value": "number | string | \"fill\" | \"xsmall\" | \"small\" | \"normal\" | \"large\"",
+                "description": "iconSizeType is used to define the size of the icon."
+            }
+        ]
     }
 }

projects/composition/src/app/api-data/cps-input.json

@@ -264,5 +264,15 @@
                 ]
             }
         }
+    },
+    "types": {
+        "description": "Defines the custom types used by the module.",
+        "values": [
+            {
+                "name": "CpsInputAppearanceType",
+                "value": "\"outlined\" | \"underlined\" | \"borderless\"",
+                "description": "CpsInputAppearanceType is used to define the border of the input field."
+            }
+        ]
     }
 }

projects/composition/src/app/api-data/cps-menu.json

@@ -125,5 +125,20 @@
                 ]
             }
         }
+    },
+    "types": {
+        "description": "Defines the custom types used by the module.",
+        "values": [
+            {
+                "name": "CpsMenuItem",
+                "value": "{\n    \"title\": \"string\",\n    \"action\": \"Function\",\n    \"icon\": \"string\",\n    \"desc\": \"string\",\n    \"url\": \"string\",\n    \"target\": \"string\",\n    \"disabled\": \"boolean\",\n    \"loading\": \"boolean\"\n}",
+                "description": "CpsMenuItem is used to define the items of the CpsMenuComponent."
+            },
+            {
+                "name": "CpsMenuAttachPosition",
+                "value": "\"tr\" | \"br\" | \"tl\" | \"bl\" | \"default\"",
+                "description": "CpsMenuAttachPosition is used to define attachment position of the CpsMenuComponent."
+            }
+        ]
     }
 }

projects/composition/src/app/api-data/cps-notification.json

@@ -1,4 +1,5 @@
 {
+    "components": {},
     "name": "CpsNotificationService",
     "description": "Service for showing notifications.",
     "methods": {
@@ -99,5 +100,85 @@
                 "description": "Clears all notifications."
             }
         ]
+    },
+    "interfaces": {
+        "description": "Defines the custom interfaces used by the module.",
+        "values": [
+            {
+                "name": "CpsNotificationConfig",
+                "description": "Configuration for the notification service.",
+                "props": [
+                    {
+                        "name": "position",
+                        "optional": true,
+                        "readonly": false,
+                        "type": "CpsNotificationPosition",
+                        "description": "Position of the notification, options are \"center\", \"top\", \"bottom\", \"left\", \"right\", \"top-left\", \"top-right\", \"bottom-left\" or \"bottom-right\"."
+                    },
+                    {
+                        "name": "appearance",
+                        "optional": true,
+                        "readonly": false,
+                        "type": "CpsNotificationAppearance",
+                        "description": "Appearance of the notification, options are \"filled\" or \"outlined\"."
+                    },
+                    {
+                        "name": "timeout",
+                        "optional": true,
+                        "readonly": false,
+                        "type": "number",
+                        "description": "The duration (in milliseconds) that the notification will be displayed before automatically closing.\nValue 0 means that the notification is persistent and will not be automatically closed."
+                    },
+                    {
+                        "name": "allowDuplicates",
+                        "optional": true,
+                        "readonly": false,
+                        "type": "boolean",
+                        "description": "Whether to allow duplicates of the same notification to be displayed within a positioned container."
+                    },
+                    {
+                        "name": "maxAmount",
+                        "optional": true,
+                        "readonly": false,
+                        "type": "number",
+                        "description": "Max amount of notifications that can be simultaneously visualized within a positioned container."
+                    },
+                    {
+                        "name": "maxWidth",
+                        "optional": true,
+                        "readonly": false,
+                        "type": "string",
+                        "description": "Max width of the notification of type number denoting pixels or string."
+                    }
+                ]
+            },
+            {
+                "name": "CpsNotificationData",
+                "description": "Defines data type for the notification data.",
+                "props": [
+                    {
+                        "name": "message",
+                        "optional": true,
+                        "readonly": false,
+                        "type": "string",
+                        "description": "Message to be displayed in the notification."
+                    },
+                    {
+                        "name": "details",
+                        "optional": true,
+                        "readonly": false,
+                        "type": "string",
+                        "description": "Details to be displayed in the notification."
+                    },
+                    {
+                        "name": "type",
+                        "optional": true,
+                        "readonly": false,
+                        "type": "CpsNotificationType",
+                        "description": "Type of the notification, options are \"warning\", \"success\", \"error\" or \"info\"."
+                    }
+                ]
+            }
+        ]
     }
 }

projects/composition/src/app/api-data/cps-radio-group.json

@@ -219,5 +219,15 @@
                 ]
             }
         }
+    },
+    "types": {
+        "description": "Defines the custom types used by the module.",
+        "values": [
+            {
+                "name": "CpsRadioOption",
+                "value": "{\n    \"value\": \"any\",\n    \"label\": \"string\",\n    \"disabled\": \"boolean\",\n    \"tooltip\": \"string\"\n}",
+                "description": "CpsRadioOption is used to define the options of the CpsRadioGroupComponent."
+            }
+        ]
     }
 }