feat: expose deprecated,readonly and platform annotations in the ts defs (#150)

Author: MarshallOfSound

package.json

@@ -34,7 +34,7 @@
     "semantic-release": "^15.13.3"
   },
   "dependencies": {
-    "@electron/docs-parser": "^0.2.1",
+    "@electron/docs-parser": "^0.4.1",
     "@types/node": "^11.13.7",
     "chalk": "^2.4.2",
     "colors": "^1.1.2",

src/dynamic-param-interfaces.ts

@@ -148,7 +148,7 @@ const flushParamInterfaces = (
         param.properties = param.properties || [];
         param.properties.forEach(paramProperty => {
           if (paramProperty.description) {
-            utils.extendArray(paramAPI, utils.wrapComment(paramProperty.description));
+            utils.extendArray(paramAPI, utils.wrapComment(paramProperty.description, paramProperty.additionalTags));
           }
 
           if (!Array.isArray(paramProperty.type) && paramProperty.type.toLowerCase() === 'object') {

src/index.ts

@@ -54,8 +54,8 @@ const appendNodeJSOverride = (outputLines: string[]) => {
   );
   utils.extendArray(outputLines, [
     '  interface ProcessVersions {',
-    '    electron: string;',
-    '    chrome: string;',
+    '    readonly electron: string;',
+    '    readonly chrome: string;',
     '  }',
   ]);
 

src/module-declaration.ts

@@ -12,6 +12,7 @@ import {
   TypeInformation,
   DetailedFunctionType,
   ElementDocumentationContainer,
+  DocumentationTag,
 } from '@electron/docs-parser';
 
 const modules: Record<string, string[]> = {};
@@ -65,7 +66,7 @@ export const generateModuleDeclaration = (
     _.concat([], module.instanceEvents || [], module.events || [])
       .sort((a, b) => a.name.localeCompare(b.name))
       .forEach(moduleEvent => {
-        utils.extendArray(moduleAPI, utils.wrapComment(moduleEvent.description));
+        utils.extendArray(moduleAPI, utils.wrapComment(moduleEvent.description, moduleEvent.additionalTags));
         let listener = 'Function';
 
         if (moduleEvent.parameters && moduleEvent.parameters.length) {
@@ -102,7 +103,7 @@ export const generateModuleDeclaration = (
             }
 
             let newType = argType || utils.typify(eventListenerArg);
-            const functionListenerArg = eventListenerArg as DetailedFunctionType &
+            const functionListenerArg = eventListenerArg as any as DetailedFunctionType &
               DocumentationBlock &
               TypeInformation;
             if (newType === 'Function') {
@@ -133,7 +134,7 @@ export const generateModuleDeclaration = (
   if (module.type === 'Element') {
     if (module.events) {
       module.events.forEach(domEvent => {
-        utils.extendArray(moduleAPI, utils.wrapComment(domEvent.description));
+        utils.extendArray(moduleAPI, utils.wrapComment(domEvent.description, domEvent.additionalTags));
         let eventType = 'Event';
 
         if (domEvent.parameters && domEvent.parameters.length) {
@@ -189,7 +190,7 @@ export const generateModuleDeclaration = (
     ['on', 'once', 'removeAllListeners', 'removeListener'].includes(moduleMethod.name);
 
   const addMethod = (moduleMethod: MethodDocumentationBlock, prefix = '') => {
-    utils.extendArray(moduleAPI, utils.wrapComment(moduleMethod.description));
+    utils.extendArray(moduleAPI, utils.wrapComment(moduleMethod.description, moduleMethod.additionalTags));
     let returnType: string | TypeInformation = returnsThis(moduleMethod) ? 'this' : 'void';
 
     if (moduleMethod.returns) {
@@ -245,6 +246,7 @@ export const generateModuleDeclaration = (
       ...module.constructorMethod,
       description: module.name,
       returns: null,
+      additionalTags: [],
     });
   }
 
@@ -273,7 +275,8 @@ export const generateModuleDeclaration = (
       .sort((a, b) => a.name.localeCompare(b.name))
       .forEach(prop => {
         const isOptional = !prop.required ? '?' : '';
-        moduleAPI.push(`${prop.name}${isOptional}: ${utils.typify(prop)};`);
+        const isReadonly = prop.additionalTags.includes(DocumentationTag.AVAILABILITY_READONLY) ? 'readonly ' : '';
+        moduleAPI.push(`${isReadonly}${prop.name}${isOptional}: ${utils.typify(prop)};`);
       });
   }
 
@@ -282,12 +285,8 @@ export const generateModuleDeclaration = (
     module.staticProperties
       .sort((a, b) => a.name.localeCompare(b.name))
       .forEach(prop => {
-        // if (prop.type === 'Class') {
-        //   moduleAPI.push(`static ${prop.name}: typeof ${prop.name};`);
-        //   generateModuleDeclaration(prop, -1, API);
-        // } else {
-        moduleAPI.push(`static ${prop.name}: ${utils.typify(prop)};`);
-        // }
+        const isReadonly = prop.additionalTags.includes(DocumentationTag.AVAILABILITY_READONLY) ? 'readonly ' : '';
+        moduleAPI.push(`static${isReadonly} ${prop.name}: ${utils.typify(prop)};`);
       });
   }
 
@@ -305,16 +304,17 @@ export const generateModuleDeclaration = (
 
         const isStatic = isStaticVersion ? 'static ' : '';
         const isOptional = utils.isOptional(p) ? '?' : '';
+        const isReadonly = p.additionalTags.includes(DocumentationTag.AVAILABILITY_READONLY) ? 'readonly ' : '';
         type = type || utils.typify(paramType);
 
-        utils.extendArray(moduleAPI, utils.wrapComment(p.description));
+        utils.extendArray(moduleAPI, utils.wrapComment(p.description, p.additionalTags));
         if (module.name === 'process' && p.name === 'versions') return;
 
         if (p.name.match(/^\d/)) {
           // Wrap key in quotes if it starts with a number, e.g. `2d_canvas`
-          moduleAPI.push(`'${isStatic}${p.name}${isOptional}': ${type};`);
+          moduleAPI.push(`'${isStatic}${isReadonly}${p.name}${isOptional}': ${type};`);
         } else {
-          moduleAPI.push(`${isStatic}${p.name}${isOptional}: ${type};`);
+          moduleAPI.push(`${isStatic}${isReadonly}${p.name}${isOptional}: ${type};`);
         }
       });
   }

src/utils.ts

@@ -7,6 +7,7 @@ import {
   DetailedObjectType,
   DocumentationBlock,
   DetailedFunctionType,
+  DocumentationTag,
 } from '@electron/docs-parser';
 import _ from 'lodash';
 import d from 'debug';
@@ -26,7 +27,7 @@ export const extendArray = <T>(arr1: T[], arr2: T[]): T[] => {
   return arr1;
 };
 
-export const wrapComment = (comment: string): string[] => {
+export const wrapComment = (comment: string, additionalTags: DocumentationTag[] = []): string[] => {
   if (!comment) return [];
   comment = comment.replace(/^\(optional\)(?: - )?/gi, '').trim();
   if (!comment) return [];
@@ -46,6 +47,34 @@ export const wrapComment = (comment: string): string[] => {
     result.push(` * ${comment.substring(0, index)}`);
     comment = comment.substring(index + 1);
   }
+  if (additionalTags.length) {
+    result.push(' *');
+    const nodePlatforms: string[] = [];
+    result.push(...(additionalTags.map(tag => {
+      switch (tag) {
+        case DocumentationTag.STABILITY_DEPRECATED:
+          return ' * @deprecated';
+        case DocumentationTag.STABILITY_EXPERIMENTAL:
+          return ' * @experimental';
+        case DocumentationTag.OS_LINUX:
+          nodePlatforms.push('linux');
+          break;
+        case DocumentationTag.OS_MACOS:
+          nodePlatforms.push('darwin');
+          break;
+        case DocumentationTag.OS_MAS:
+          nodePlatforms.push('mas');
+          break;
+        case DocumentationTag.OS_WINDOWS:
+          nodePlatforms.push('win32');
+          break;
+      }
+      return '';
+    }).filter(tag => tag)))
+    if (nodePlatforms.length) {
+      result.push(` * @platform ${nodePlatforms.join(',')}`);
+    }
+  }
   return result.concat(' */');
 };
 

yarn.lock

@@ -27,10 +27,10 @@
     read-pkg "^4.0.0"
     registry-auth-token "^3.3.1"
 
-"@electron/docs-parser@^0.2.1":
-  version "0.2.1"
-  resolved "https://registry.yarnpkg.com/@electron/docs-parser/-/docs-parser-0.2.1.tgz#14bcc7ec5afa1b2e89dc6dbdb7152dc74c2b5c46"
-  integrity sha512-vQNxIQzIudFp3TECH9TEkPZUvLrDzZO5wZPmgN5e3c69yqmMj779I86Ny8giQfY93jFpRZ/+gRqIwVfD6gFEWA==
+"@electron/docs-parser@^0.4.1":
+  version "0.4.1"
+  resolved "https://registry.yarnpkg.com/@electron/docs-parser/-/docs-parser-0.4.1.tgz#e6557a6a3899ca1168b9f2d70ad24d9ba924e4a9"
+  integrity sha512-mn4ofEvH8HNdzRMb++cUbiTkO88BAKwM0yjED3KrQ07yEl7CU1lK13qSMVSRhDzNkbg4kFTqBDjaJ57fdHlkxQ==
   dependencies:
     "@types/markdown-it" "^0.0.7"
     chai "^4.2.0"
@@ -1513,12 +1513,7 @@ [email protected], escape-string-regexp@^1.0.2, escape-string-regexp@^1
   resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz#1b61c0562190a8dff6ae3bb2cf0200ca130b86d4"
   integrity sha1-G2HAViGQqN/2rjuyzwIAyhMLhtQ=
 
-esprima@^4.0.0:
-  version "4.0.1"
-  resolved "https://registry.yarnpkg.com/esprima/-/esprima-4.0.1.tgz#13b04cdb3e6c5d19df91ab6987a8695619b0aa71"
-  integrity sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==
-
-esprima@~4.0.0:
+esprima@^4.0.0, esprima@~4.0.0:
   version "4.0.1"
   resolved "https://registry.yarnpkg.com/esprima/-/esprima-4.0.1.tgz#13b04cdb3e6c5d19df91ab6987a8695619b0aa71"
   integrity sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==
@@ -2693,15 +2688,7 @@ java-properties@^0.2.9:
   resolved "https://registry.yarnpkg.com/java-properties/-/java-properties-0.2.10.tgz#2551560c25fa1ad94d998218178f233ad9b18f60"
   integrity sha512-CpKJh9VRNhS+XqZtg1UMejETGEiqwCGDC/uwPEEQwc2nfdbSm73SIE29TplG2gLYuBOOTNDqxzG6A9NtEPLt0w==
 
-[email protected], js-yaml@^3.9.0:
-  version "3.13.1"
-  resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.13.1.tgz#aff151b30bfdfa8e49e05da22e7415e9dfa37847"
-  integrity sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==
-  dependencies:
-    argparse "^1.0.7"
-    esprima "^4.0.0"
-
-js-yaml@^3.13.0:
+[email protected], js-yaml@^3.13.0, js-yaml@^3.9.0:
   version "3.13.1"
   resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.13.1.tgz#aff151b30bfdfa8e49e05da22e7415e9dfa37847"
   integrity sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==
@@ -2969,9 +2956,9 @@ libnpx@^10.2.0:
     yargs "^11.0.0"
 
 linkify-it@^2.0.0:
-  version "2.1.0"
-  resolved "https://registry.yarnpkg.com/linkify-it/-/linkify-it-2.1.0.tgz#c4caf38a6cd7ac2212ef3c7d2bde30a91561f9db"
-  integrity sha512-4REs8/062kV2DSHxNfq5183zrqXMl7WP0WzABH9IeJI+NLm429FgE1PDecltYfnOoFDFlZGh2T8PfZn0r+GTRg==
+  version "2.2.0"
+  resolved "https://registry.yarnpkg.com/linkify-it/-/linkify-it-2.2.0.tgz#e3b54697e78bf915c70a38acd78fd09e0058b1cf"
+  integrity sha512-GnAl/knGn+i1U/wjBz3akz2stz+HrHLsxMwHQGofCDfPvlf+gDKN58UtfmUquTY4/MXeE2x7k19KQmeoZi94Iw==
   dependencies:
     uc.micro "^1.0.1"