fix: rendering issues

Fix a few rendering issues
cdklabs · Jun 14, 2020 · 239fe1d · 239fe1d
1 parent 34da105
commit 239fe1d
Show file tree

Hide file tree

Showing 7 changed files with 2,238 additions and 2,624 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -7,6 +7,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - run: npx projen@0.1.19
+      - run: npx projen@0.1.21
       - run: yarn install --frozen-lockfile
       - run: yarn build
+      - name: Anti-tamper check
+        run: git diff --exit-code
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -9,9 +9,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - run: npx projen@0.1.19
+      - run: npx projen@0.1.21
       - run: yarn install --frozen-lockfile
       - run: yarn build
+      - name: Anti-tamper check
+        run: git diff --exit-code
       - name: Upload artifact
         uses: actions/upload-artifact@v1
         with:

diff --git a/lib/render/home.ts b/lib/render/home.ts
@@ -34,14 +34,17 @@ export class Home extends Page {
         return;
       }
 
-      lines.push();
+      lines.push('');
       lines.push(`**${title}**`);
+      lines.push('');
       lines.push('Name|Description');
       lines.push('----|-----------');
 
       for (const type of collection) {
-        lines.push(`${self.typeLink(type)}|${type.docs.summary}`);
+        lines.push(`${self.typeLink(type)}|${type.docs.summary.trim() || '*No description*'}`);
       }
+
+      lines.push('');
     }
   }
 }
diff --git a/lib/render/klass.ts b/lib/render/klass.ts
@@ -1,7 +1,7 @@
 import * as jsiiReflect from 'jsii-reflect';
 import { flatMap, compareByKeys, isStatic } from './util';
 import { Page, RenderContext } from './page';
-import { elementAnchorLink, elementAnchor } from './links';
+import { elementAnchor } from './links';
 
 abstract class Base extends Page {
   protected renderProperties(properties: jsiiReflect.Property[], caption: string) {
@@ -23,10 +23,11 @@ abstract class Base extends Page {
 
     function _propertiesTableLine(property: jsiiReflect.Property) {
       const name = self.renderElementName(property.name);
-      let summary = property.docs.summary;
+      let summary = property.docs.summary.trim();
 
       if (property.optional) {
-        summary += '<br/><br/>' + self.renderDefault(property.docs.docs.default);
+        summary += (summary.length > 0 ? '<br/>' : '')
+          + self.renderDefault(property.docs.docs.default);
       }
 
       return self.tableRow(
@@ -41,7 +42,7 @@ abstract class Base extends Page {
     if (!c.base) { return []; }
 
     return [
-      `**Extends**: ${this.typeLink(c.base)}`,
+      `${this.underline('Extends')}: ${this.typeLink(c.base)}`,
     ];
   }
 
@@ -56,7 +57,7 @@ abstract class Base extends Page {
     if (implementors.length === 0) { return []; }
 
     return [
-      `**Implemented by**: ${implementors.map(x => this.typeLink(x)).join(', ')}`,
+      `${this.underline('Implemented by')}: ${implementors.map(x => this.typeLink(x)).join(', ')}`,
     ];
   }
 
@@ -67,22 +68,22 @@ abstract class Base extends Page {
 
     return [
       this.headingB(caption),
-      '',
-      'Name | Description',
-      '-----|-----',
-      ...methods.map(m => this.methodTableLine(m)),
+      // '',
+      // 'Name | Description',
+      // '-----|-----',
+      // ...methods.map(m => this.methodTableLine(m)),
       '',
       ...methods.map(m => this.methodDetail(m)),
     ];
   }
 
-  private methodTableLine(method: jsiiReflect.Callable) {
-    const text = `[${this.renderElementName(method.name + '()')}](${elementAnchorLink(method)})`;
-    return this.tableRow(
-      `${text}${this.renderStability(method)}`,
-      method.docs.summary,
-    );
-  }
+  // private methodTableLine(method: jsiiReflect.Callable) {
+  //   const text = `[${this.renderElementName(method.name + '()')}](${elementAnchorLink(method)})`;
+  //   return this.tableRow(
+  //     `${text}${this.renderStability(method)}`,
+  //     method.docs.summary,
+  //   );
+  // }
 
   protected methodDetail(method: jsiiReflect.Callable, includeHeader = true) {
     const keywordArgsType = method.parameters.length > 0 && method.parameters[method.parameters.length -1].type.type;
@@ -104,13 +105,16 @@ abstract class Base extends Page {
     }
 
     return [
-      includeHeader ? '\n---' : '',
       includeHeader ? this.headingC(`${this.methodSignature(method)}${this.renderStability(method)} ${elementAnchor(method)}`) : '',
       method.docs.toString(),
-      '```',
+      '',
+      this.underline('Usage:'),
+      '',
+      '```ts',
       `${this.methodSignature(method, { long: true, verbatim: true })}`,
       '```',
       '',
+      this.underline('Parameters:'),
       ...method.parameters.map(p => [
         '*',
         this.renderElementName(p.name),
@@ -120,14 +124,13 @@ abstract class Base extends Page {
       ...keywordArguments,
       '',
       ...method instanceof jsiiReflect.Method ? [
-        !method.returns.type.void ? '*Returns*' : '',
+        !method.returns.type.void ? this.underline('Returns') + ':' : '',
         !method.returns.type.void ? '* ' + this.typeReferenceLink(method.returns.type) : '',
       ] : [],
       '',
     ].join('\n');
   }
 
-
   /**
    * Find all public static methods that can produce a type like this
    *
@@ -145,7 +148,7 @@ abstract class Base extends Page {
     if (factories.length === 0) { return []; }
 
     return [
-      `**Obtainable from**: ${factories.map(x => this.methodLink(x)).join(', ')}`,
+      `${this.underline('Obtainable from')}: ${factories.map(x => this.methodLink(x)).join(', ')}`,
     ];
   }
 }
@@ -167,8 +170,8 @@ export class ClassPage extends Base {
       ...this.renderFactories(klass),
       '',
       ...this.renderConstructor(klass),
-      ...this.renderProperties(klass.allProperties.filter(documentableProperty), 'Properties'),
-      ...this.renderMethods(classMethods(klass).filter(documentableMethod)),
+      ...this.renderProperties(klass.ownProperties.filter(documentableProperty), 'Properties'),
+      ...this.renderMethods(klass.ownMethods.filter(documentableMethod)),
     ];
   }
 
@@ -187,7 +190,7 @@ export class ClassPage extends Base {
     if (ifaces.length === 0) { return []; }
 
     return [
-      `**Implements**: ${ifaces.map(x => this.typeLink(x)).join(', ')}`,
+      `${this.underline('Implements')}: ${ifaces.map(x => this.typeLink(x)).join(', ')}`,
     ];
   }
 
@@ -243,10 +246,6 @@ function publicOrDefinedHere(p: jsiiReflect.Callable | jsiiReflect.Property) {
   throw new Error(`Unknown callable: ${p}`);
 }
 
-function classMethods(c: jsiiReflect.ClassType) {
-  return c.allMethods;
-}
-
 function isClassType(x: jsiiReflect.Type): x is jsiiReflect.ClassType {
   // Need this function because my TypeScript doesn't propagate the type guard
   // through a method.

diff --git a/lib/render/page.ts b/lib/render/page.ts
@@ -1,5 +1,5 @@
 import * as jsiiReflect from 'jsii-reflect';
-import { Stability } from 'jsii-spec';
+import { Stability } from '@jsii/spec';
 import { isStatic } from './util';
 import { elementAnchorLink, elementAnchor } from './links';
 
@@ -43,20 +43,22 @@ export abstract class Page {
     }
 
     lines.push(...this.render());
-    return lines.join('\n');
+
+    return lines.map(x => x ?? '').join('\n');
   }
 
   protected abstract render(): string[];
 
   protected renderDefault(x: string = '') {
+    x = x.replace(/\n/g, ' ');
     x = x.trim();
     if (x.startsWith('- ')) { x = x.substr(2); }
     x = x.trim();
 
     if (x) {
-      return '*Default*: ' + x;
+      return this.underline(this.italic('Default')) + ': ' + x;
     } else {
-      return '*Optional*'
+      return this.underline(this.italic('Optional'));
     }
   }
 
@@ -88,6 +90,14 @@ export abstract class Page {
     const heading = '#'.repeat(number + level - 1);
     return `${heading} ${caption}\n`;
   }
+
+  protected underline(text: string) {
+    return `<span style="text-decoration: underline">${text}</span>`;
+  }
+
+  protected italic(text: string) {
+    return `*${text}*`;
+  }
 
   protected renderElementName(name: string) {
     return `**${name}**`;
@@ -107,7 +117,7 @@ export abstract class Page {
     const self = this;
     const name = method.name;
 
-    const visibility = method.protected ? 'protected ' : 'public ';
+    const visibility = method.protected ? 'protected ' : '';
     const paramRenderer = options.long ? fullParam : shortParam;
     const parameters = method.parameters.map(paramRenderer).join(', ');
     const returnDecl = options.long && method instanceof jsiiReflect.Method ? ': ' + this.formatTypeSimple(method.returns.type) : '';
@@ -193,13 +203,14 @@ export abstract class Page {
 
 }
 
-function mkIcon(icon: string, tooltip: string) {
-  return `<span title="${htmlEncode(tooltip)}">${icon}</span>`;
+function mkIcon(icon: string, _tooltip: string) {
+  // return `<span title="${htmlEncode(tooltip)}">${icon}</span>`;
+  return icon;
 }
 
-function htmlEncode(x: string) {
-  return x.replace(/[\u00A0-\u9999<>\&]/gim, i => '&#' + i.charCodeAt(0) + ';');
-}
+// function htmlEncode(x: string) {
+//   return x.replace(/[\u00A0-\u9999<>\&]/gim, i => '&#' + i.charCodeAt(0) + ';');
+// }
 
 export interface SignatureOptions {
   /**