@progress/kendo-typescript-api-tasks 1.1.2-dev.9 → 2.0.1-dev.0

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.0.0](https://github.com/telerik/kendo-build-tasks/compare/@progress/kendo-typescript-api-tasks@1.1.1...@progress/kendo-typescript-api-tasks@2.0.0) (2023-10-27)
+
+
+### Bug Fixes
+
+* **typescript-api-tasks:** list file location in warnings ([79d12fc](https://github.com/telerik/kendo-build-tasks/commit/79d12fcba72bdd8fda6f1933828adc41d920bf49))
+* **typescript-api-tasks:** read comments from all base types ([e1dd708](https://github.com/telerik/kendo-build-tasks/commit/e1dd70810d01a9f4462b3d6ed988478ce70daf3c))
+* **typescript-api-tasks:** support decorators for TS 4.6 ([12046b7](https://github.com/telerik/kendo-build-tasks/commit/12046b768016b75612e1e7ca8779bc39cb70dffb))
+
+
+### Features
+
+* **kendo-typescript-api-tasks:** upgrade to Typedoc 0.25 ([802666f](https://github.com/telerik/kendo-build-tasks/commit/802666f570e2e4f46fa532a57393ffa18b5902f5))
+
+
+### BREAKING CHANGES
+
+* **kendo-typescript-api-tasks:** No longer compatible with TypeScript < 4.6
+
+
+
+
+
 ## [1.1.1](https://github.com/telerik/kendo-build-tasks/compare/@progress/kendo-typescript-api-tasks@1.1.0...@progress/kendo-typescript-api-tasks@1.1.1) (2022-12-05)
 
 

package/index.js

@@ -1,3 +1,5 @@
+"use strict";
+
 const execSync = require('child_process').execSync;
 const fs = require('fs');
 const path = require('path');
@@ -18,7 +20,8 @@ const defaultConfig = {
     }
 };
 
-module.exports = (gulp, userConfig) => {
+module.exports.ReflectionKind = typedoc.ReflectionKind;
+module.exports.addAPITasks = (gulp, userConfig) => {
     const series = gulp.series;
 
     const config = merge({}, defaultConfig, userConfig);
@@ -33,11 +36,17 @@ module.exports = (gulp, userConfig) => {
             ...(config.externalApi || [])
         ];
 
-        const app = new typedoc.Application();
-        app.options.addReader(new typedoc.TSConfigReader());
-        app.bootstrap({ ...config.typedoc, entryPoints });
+        let app = await typedoc.Application.bootstrapWithPlugins(
+            {
+                ...config.typedoc,
+                entryPoints,
+                plugin: [ path.join(__dirname, './lib/plugins/decorators.js') ]
+            }, [
+                new typedoc.TSConfigReader()
+            ]
+        );
 
-        const project = app.convert();
+        const project = await app.convert();
         if (!project) {
             done(new Error('Unable to initialize TypeDoc.'));
             return;

package/lib/class-page.js

@@ -17,8 +17,8 @@ const classPage = (member, meta) => {
     let constructors = null;
     if (member.children) {
         constructors = mapConstructors(member);
-        methods = mapMethods(member.children, member.name);
-        props = mapProps(member.children, member.name);
+        methods = mapMethods(member.children, member);
+        props = mapProps(member.children, member);
     }
 
     return classTemplate(Object.assign({}, meta, {

package/lib/comment.js

@@ -8,12 +8,12 @@ const commentTemplate = template.compileFrom('comment-tags.hbs');
 
 const commentTags = (comment, member) =>
     commentTemplate({
-        tags: comment.tags.map(tag => {
-            let text = tag.text.trim();
+        tags: comment.blockTags.map(tag => {
+            let text = tag.content.map(c => c.text).join('').trim();
 
-            if (tag.tag === 'example') {
+            if (tag.tag === '@example') {
                 text = text.replace(/_@/g, '@');
-            } else if (tag.tag === 'see') {
+            } else if (tag.tag === '@see') {
                 const linkSlug = slug(member.packageName, text);
                 text = `\n\nSee [${text}]({% slug ${linkSlug} %})`;
             } else {
@@ -26,7 +26,15 @@ const commentTags = (comment, member) =>
         })
     });
 
-const formatComment = (member, parentName, memberKind) => {
+const commentSummary = (comment) => {
+    if (!comment.summary) {
+        return '';
+    }
+
+    return comment.summary.map(c => c.text).join('').trim();
+};
+
+const formatComment = (member, parent) => {
     let signatures;
     if (member.type && member.type.declaration) {
         signatures = member.type.declaration.signatures;
@@ -35,17 +43,14 @@ const formatComment = (member, parentName, memberKind) => {
     const comment = member.comment || signatures && signatures[0] && signatures[0].comment;
 
     if (!comment) {
-        warn(member, parentName, memberKind);
+        warn(member, parent);
 
         return '';
     }
 
-    let output = comment.shortText || "";
-    if (comment.text) {
-        output += '\n\n' + comment.text;
-    }
+    let output = commentSummary(comment);
 
-    if (comment.tags) {
+    if (comment.blockTags) {
         output += commentTags(comment, member);
     }
 

package/lib/component-page.js

@@ -44,10 +44,10 @@ const componentPage = (component, meta) => {
     let events;
     let methods;
     if (component.children) {
-        fields = ignoreWithoutComment(mapProps(component.children.filter(isField), component.name));
-        inputs = mapProps(component.children.filter(isInput), component.name);
-        events = mapProps(component.children.filter(isEvent), component.name);
-        methods = mapMethods(component.children, component.name);
+        fields = ignoreWithoutComment(mapProps(component.children.filter(isField), component));
+        inputs = ignoreWithoutComment(mapProps(component.children.filter(isInput), component));
+        events = mapProps(component.children.filter(isEvent), component);
+        methods = mapMethods(component.children, component);
     }
 
     return componentTemplate(Object.assign({}, meta, {

package/lib/generator.js

@@ -1,3 +1,5 @@
+"use strict";
+
 const fs = require('fs');
 const mkdirp = require('mkdirp');
 const path = require('path');
@@ -5,11 +7,12 @@ const indexPage = require('./index-page.js');
 const memberPage = require('./member-page.js');
 const slug = require('./slug.js');
 const utils = require('./utils.js');
+const { ReflectionKind } = require('typedoc');
 
-const moduleFilter = (module) => module.children;
+const moduleFilter = (module) => module.kind === ReflectionKind.Module && module.children;
 
 const kind = (member, module) => {
-    let kind = member.kindString.toLowerCase();
+    let kind = ReflectionKind.singularString(member.kind).toLowerCase();
     const notBaseType = kind !== 'function' && kind !== 'enumeration' && kind !== 'interface' &&
         kind !== 'object literal' && kind !== 'module';
 
@@ -30,10 +33,10 @@ const kind = (member, module) => {
 
 const addTypeSlug = (element, knownTypes, typeLinks) => {
     if (element.type === 'reference' ||
-        (typeof element.type !== 'string' && knownTypes[element.id])) {
-        const type = knownTypes[element.id];
+        (typeof element.type !== 'string' && knownTypes[element.target])) {
+        const type = knownTypes[element.target];
         if (type) {
-            element.typeSlug = type.slug;
+            element.slug = type.slug;
         } else if (typeLinks[element.name]) {
             element.typeLink = typeLinks[element.name];
         }
@@ -88,24 +91,27 @@ const normalizeUnionReferences = (element, members) => {
 const normalizeMembers = (members) => {
     traverseElements(members, (element) => {
         normalizeUnionReferences(element, members);
+        mergeBaseOptions(element, members);
 
-        if (!element.comment && element.implementationOf) {
-            const interfaceName = element.implementationOf.name.split('.')[0];
-            const interfaceOptions = members.find((child) => child.name === interfaceName);
-
-            if (interfaceOptions) {
-                const baseOption = interfaceOptions.children.find(child => child.name === element.name);
-                if (baseOption) {
-                    mergeComments(element, baseOption);
-                }
-            }
+        if (!element.comment && element.kind === ReflectionKind.Accessor) {
+            element.comment = (element.setSignature || {}).comment || (element.getSignature || {}).comment || [];
         }
+    });
+};
+
+const mergeBaseOptions = (element, members) => {
+    if (!element.comment && (element.implementationOf || element.inheritedFrom)) {
+        const interfaceName = (element.implementationOf || element.inheritedFrom).name.split('.')[0];
+        const interfaceOptions = members.find((child) => child.name === interfaceName);
 
-        if (!element.comment && element.kindString === 'Accessor') {
-            const accessor = element.getSignature || element.setSignature || [];
-            element.comment = accessor[0].comment;
+        if (interfaceOptions) {
+            const baseOption = interfaceOptions.children.find(child => child.name === element.name);
+            if (baseOption) {
+                mergeBaseOptions(baseOption, members);
+                mergeComments(element, baseOption);
+            }
         }
-    });
+    }
 };
 
 const mergeComments = (root, src) => {
@@ -140,9 +146,10 @@ const extractMembers = (packageName, modules, config) => {
 
     const models = nonEmptyModules.map(module => module
         .children
-        .filter(child => child.kindString !== "Reference")
+        .filter(child => child.kind !== ReflectionKind.Reference)
         .filter(child => child.name !== 'core')
         .filter(child => child.sources && !child.sources[0].fileName.includes('prosemirror'))
+        .filter(child => child.sources && !child.sources[0].fileName.includes('@types'))
         .map(child => {
             const fullName = moduleFullName(module.name, packageName, rootModules);
 
@@ -158,6 +165,7 @@ const extractMembers = (packageName, modules, config) => {
                 packageName: fullName,
                 url: `${child.name}`,
                 signatures: child.signatures,
+                sources: child.sources,
                 slug: slug(fullName, child.name),
                 typeParameter: child.typeParameter
             };
@@ -190,7 +198,7 @@ const namespacesAsModules = data => {
         .children
         .filter(child => child.name !== 'core')
         .forEach(child => {
-            if (child.kindString === 'Module' && child.children) {
+            if (child.kind === ReflectionKind.Module && child.children) {
                 modules.push(child);
             }
         })

package/lib/is-constructor.js

@@ -1,9 +1,10 @@
 "use strict";
 
+const { ReflectionKind } = require('typedoc');
 const isPublic = require('./is-public');
 
 const isConstructor = (prop) =>
-    prop.kindString && prop.kindString === 'Constructor' && isPublic(prop);
+    prop.kind && prop.kind === ReflectionKind.Constructor && isPublic(prop);
 
 module.exports = isConstructor;
 

package/lib/is-method.js

@@ -1,10 +1,11 @@
 "use strict";
 
+const { ReflectionKind } = require('typedoc');
 const isPublic = require('./is-public');
 const isInput = require('./is-input');
 
 const isMethod = (prop) =>
-    prop.kindString && prop.kindString === 'Method' && isPublic(prop) && !isInput(prop);
+    prop.kind && prop.kind === ReflectionKind.Method && isPublic(prop) && !isInput(prop);
 
 module.exports = isMethod;
 

package/lib/map-constructors.js

@@ -1,12 +1,13 @@
-'use strict';
+"use strict";
 
+const { ReflectionKind } = require('typedoc');
 const comment = require('./comment');
 const isPublic = require('./is-public');
 const types = require('./type-utils');
 const utils = require('./utils');
 
 const isConstructor = (prop) =>
-    prop.kindString && prop.kindString === 'Constructor' && isPublic(prop);
+    prop.kind && prop.kind === ReflectionKind.Constructor && isPublic(prop);
 
 const mapConstructors = (member) => {
     if (member.decorators && member.decorators.find(d => d.name === 'NgModule')) {
@@ -14,16 +15,14 @@ const mapConstructors = (member) => {
         return [];
     }
 
-    return utils.flatten(member.children.filter(isConstructor).map(ctr => {
-        const source = `${member.name}.constructor`;
-
-        return ctr.signatures.map((signature) => ({
+    return utils.flatten(member.children.filter(isConstructor).map(ctr =>
+        ctr.signatures.map((signature) => ({
             signature: types.callSignature(signature),
-            comment: comment(signature, source),
+            comment: comment(signature),
             name: types.fullName(member),
-            params: types.params(signature, source)
-        }));
-    }));
+            params: types.params(signature)
+        }))
+    ));
 };
 
 module.exports = mapConstructors;

package/lib/map-methods.js

@@ -6,16 +6,14 @@ const isMethod = require('./is-method.js');
 const returnType = require('./return-type');
 const utils = require('./utils');
 
-const mapMethods = (children, parentName) =>
+const mapMethods = (children, parent) =>
     utils.flatten(children.filter(isMethod).map(method => {
         const name = method.name;
-        const source = `${parentName}.${name}`;
-
         return method.signatures.map((signature) => ({
-            comment: comment(signature, source),
+            comment: comment(signature, parent),
             name: name,
-            returns: returnType(signature, source),
-            params: types.params(signature, source)
+            returns: returnType(signature, parent),
+            params: types.params(signature, parent)
         }));
     }));
 

package/lib/map-props.js

@@ -1,5 +1,6 @@
 "use strict";
 
+const { ReflectionKind } = require('typedoc');
 const comment = require('./comment');
 const types = require('./type-utils');
 const isConstructor = require('./is-constructor');
@@ -9,22 +10,22 @@ const isMethod = require('./is-method');
 const isPublic = require('./is-public');
 
 const defaultValue = prop => {
-    const { comment: { tags = [] } = {} } = prop;
-    const { text = '' } = tags.find(t => t.tag === 'default') || {};
+    const { comment: { blockTags = [] } = {} } = prop;
+    const { content = [ { text: '' } ] } = blockTags.find(t => t.tag === '@default') || {};
 
-    return text && text.trim();
+    return content && content.map(c => c.text).join(' ').replace(/```ts\n/g, '').replace(/\n```/g, '').trim();
 };
 
 const accessor = signature => (Array.isArray(signature) ? signature[0] : signature);
 
 const isProp = (prop) => isPublic(prop) && !isConstructor(prop) && !isMethod(prop);
-const mapProps = (children, parentName) =>
+const mapProps = (children, parent) =>
     children.filter(isProp).map(prop => {
         let type;
         let commentProp = prop;
         if (prop.type) {
             type = types.typeString(prop);
-        } else if (prop.kindString === 'Accessor') {
+        } else if (prop.kind === ReflectionKind.Accessor) {
             const getter = prop.getSignature;
             const setter = prop.setSignature;
 
@@ -33,7 +34,7 @@ const mapProps = (children, parentName) =>
                 accessor(setter).parameters[0] :
                 accessor(getter)
             );
-        } else if (prop.kindString === 'Method') {
+        } else if (prop.kind === ReflectionKind.Method) {
             type = types.callType(prop.signatures[0]);
             commentProp = prop.signatures[0];
         }
@@ -41,9 +42,9 @@ const mapProps = (children, parentName) =>
         let name = prop.name;
         if (isInput(prop) || isEvent(prop)) {
             const inputArgs = prop.decorators ? prop.decorators[0].arguments : {};
-            if (inputArgs.bindingPropertyName) {
+            if (inputArgs.obj) {
                 /* eslint-disable no-eval */
-                name = eval(inputArgs.bindingPropertyName);
+                name = eval(inputArgs.obj);
             }
         }
 
@@ -55,7 +56,7 @@ const mapProps = (children, parentName) =>
             name: name,
             type: type,
             defaultValue: defaultValue(prop),
-            comment: comment(commentProp, parentName)
+            comment: comment(commentProp, parent)
         };
     });
 

package/lib/plugins/decorators.js

@@ -0,0 +1,44 @@
+const td = require('typedoc');
+const ts = td.TypeScript;
+
+/** @param {td.Application} app */
+exports.load = function(app) {
+    // Add decorator info to reflections
+    app.converter.on(td.Converter.EVENT_CREATE_DECLARATION, addDecoratorInfo);
+
+    // Add decorator info to serialized json
+    app.serializer.addSerializer({
+        priority: 0,
+        supports(item) {
+            return item instanceof td.DeclarationReflection;
+        },
+        toObject(item, obj) {
+            if (item.decorators) {
+                obj.decorators = item.decorators;
+            }
+            return obj;
+        },
+    });
+};
+
+function addDecoratorInfo(context, decl) {
+    const symbol = context.project.getSymbolFromReflection(decl);
+    if (!symbol) {
+        return;
+    }
+
+    const declaration = symbol.valueDeclaration;
+    if (!declaration) {
+        return;
+    }
+
+    const decorators = (declaration.decorators ?? declaration.modifiers ?? [])
+        .filter(ts.isDecorator).map((d) => ({
+            name: d.expression.expression.getText(),
+            arguments: { obj: d.expression.arguments[0]?.getText() }
+        }));
+
+    if (decorators && decorators.length > 0) {
+        decl.decorators = decorators;
+    }
+}

package/lib/react/component-page.js

@@ -14,8 +14,8 @@ const componentPage = (component, meta) => {
     let properties;
     let methods;
     if (component.children) {
-        properties = mapProps(component.children.filter(isField), component.name);
-        methods = mapMethods(component.children, component.name);
+        properties = mapProps(component.children.filter(isField), component);
+        methods = mapMethods(component.children, component);
     }
 
     return componentTemplate(Object.assign({}, meta, {

package/lib/return-type.js

@@ -2,28 +2,28 @@
 
 const types = require('./type-utils.js');
 const utils = require('./utils.js');
+const source = require('./source');
 
-const returnType = (definition, parentName) => {
+const returnType = (definition, parent) => {
     if (definition.type.name === 'void') {
         return undefined;
     }
 
-    let comment;
-    if (definition.comment) {
-        comment = definition.comment.returns;
+    let tag;
+    if (definition.comment && definition.comment.blockTags) {
+        tag = definition.comment.blockTags.find(t => t.tag === '@returns');
     }
 
-    if (!comment && definition.type.name !== 'void') {
-        let source = `${definition.name}`;
-        if (parentName) {
-            source = `${parentName } - ${source}`;
-        }
-        utils.warn('Undocumented return type', source);
+    let comment = '';
+    if ((!tag && definition.type.name !== 'void') || (tag && tag.content.length === 0)) {
+        utils.warn('Undocumented return type', source(definition, parent));
+    } else {
+        comment = tag.content.map(c => c.text).join('').trim();
     }
 
     return {
         type: types.typeString(definition),
-        comment: comment
+        comment
     };
 };
 

package/lib/source.js

@@ -0,0 +1,13 @@
+const source = (member, parent) => {
+    const source = member.sources[0];
+    let sourceFile = `${source.fileName}:${source.line}`;
+    if (parent) {
+        const parentSource = parent.sources[0];
+        if (parentSource.fileName !== source.fileName) {
+            sourceFile = `${parentSource.fileName}:${parentSource.line} -> ` + sourceFile;
+        }
+    }
+    return `'${member.name}' ${sourceFile}`;
+};
+
+module.exports = source;

package/lib/type-utils.js

@@ -1,5 +1,6 @@
 "use strict";
 
+const { ReflectionKind } = require('typedoc');
 const comment = require('./comment');
 
 const unionTypes = (member) =>
@@ -34,9 +35,9 @@ const anonParams = (definition) => {
     return params;
 };
 
-const params = (definition, parentName) => {
+const params = (definition, parent) => {
     const paramComment = (param) =>
-        comment(param, parentName, 'parameter').trim();
+        comment(param, parent, 'parameter').trim();
 
     const params = anonParams(definition);
     params.forEach((param) => {
@@ -78,8 +79,8 @@ const callType = (definition) => {
 
 const typeName = (type) => {
     const name = type.name;
-    if (type.typeSlug) {
-        return `[${ name }]({% slug ${ type.typeSlug } %})`;
+    if (type.slug) {
+        return `[${ name }]({% slug ${ type.slug } %})`;
     } else if (type.typeLink) {
         return `[${ name }](${ type.typeLink })`;
     } else if (type.type === 'array') {
@@ -104,7 +105,7 @@ const singleTypeString = (type) => {
         const decl = type.declaration;
         if (decl.signatures) {
             const sig = decl.signatures[0];
-            if (decl.name === '__type' && sig.kindString === 'Call signature') {
+            if (decl.name === '__type' && sig.kind === ReflectionKind.CallSignature) {
                 return callType(sig);
             }
         } else if (decl.indexSignature) {
@@ -139,7 +140,7 @@ const singleTypeString = (type) => {
 const typeString = (prop) => {
     const type = prop.type;
 
-    if (!type && prop.kindString === 'Method') {
+    if (!type && prop.kind === ReflectionKind.Method) {
         return singleTypeString(prop.signatures[0]);
     }
 

package/lib/warn.js

@@ -2,20 +2,15 @@
 
 const utils = require('./utils.js');
 const rules = require('./warning-rules.js');
+const source = require('./source');
 
 const runner = rules => member =>
     rules.reduce((result, rule) => result && rule(member), true);
 
-const warn = (member, parentName, kind = 'member') => {
+const warn = (member, parent, kind = 'member') => {
     const shouldWarn = runner(rules);
-    let source = member.name;
-
-    if (parentName) {
-        source = `${parentName}.${source}`;
-    }
-
     if (shouldWarn(member)) {
-        utils.warn(`Undocumented ${kind}`, source);
+        utils.warn(`Undocumented ${kind}`, source(member, parent));
     }
 };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@progress/kendo-typescript-api-tasks",
   "description": "Kendo UI API docs package gulp tasks",
-  "version": "1.1.2-dev.9+1964951",
+  "version": "2.0.1-dev.0+f675627",
   "author": "Progress",
   "license": "Apache-2.0",
   "main": "index.js",
@@ -14,7 +14,7 @@
     "API Generation"
   ],
   "peerDependencies": {
-    "typescript": "4.0.x || 4.1.x || 4.2.x || 4.3.x || 4.4.x || 4.5.x || 4.6.x || 4.7.x"
+    "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x"
   },
   "dependencies": {
     "glob": "^8.0.3",
@@ -22,7 +22,7 @@
     "handlebars": "^4.7.7",
     "lodash": "^4.17.21",
     "mkdirp": "^1.0.4",
-    "typedoc": "0.22.15"
+    "typedoc": "0.25.2"
   },
   "overrides": {
     "chokidar": "^3.0.0",
@@ -37,7 +37,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "jest-cli": "^29.2.2"
+    "jest-cli": "^29.2.2",
+    "typescript": "5.2.2"
   },
-  "gitHead": "19649510b5438309e3e450b003fdcb2de671dc06"
+  "gitHead": "f675627f612cd05d7c8c46c1058840a11b7147cb"
 }