feat(api): Add decorator processor

Author: BrunnerLivio

compiler/api/index.ts

@@ -73,6 +73,7 @@ function postProcessors(postProcessHtml: any, autoLinkCode: any, API_DOC_TYPES:
   postProcessHtml.plugins = [
     require('./post-processors/autolink-headings'),
     autoLinkCode,
+    require('./post-processors/codeFormatting'),
   ];
 }
 
@@ -131,6 +132,7 @@ const nestjs = new Package('nestjs', [
   .processor(require('./processors/shortDescription'))
   .processor(require('./processors/removeInjectableConstructors'))
   .processor(require('./processors/processModuleDocs'))
+  .processor(require('./processors/processDecorators'))
   .processor(require('./processors/computeOutputPath'))
   .processor(require('./processors/fixInternalDocumentLinks'))
 

compiler/api/post-processors/codeFormatting.ts

@@ -0,0 +1,36 @@
+const has = require('hast-util-has-property');
+const is = require('hast-util-is-element');
+const slug = require('rehype-slug');
+const visit = require('unist-util-visit');
+
+const hasClass = (node, cls) => {
+  const className = node.properties.className;
+  return className && className.includes(cls);
+};
+
+const addClass = (node, cls) => {
+  if (!node.properties.className) {
+    node.properties.className = '';
+  }
+  node.properties.className += ' ' + cls;
+};
+
+const link = options => tree =>
+  visit(tree, node => {
+    if (
+      is(node, 'pre') &&
+      !hasClass(node, 'language-typescript') &&
+      node.children.find(child => child.tagName === 'code')
+    ) {
+      addClass(node, 'language-typescript');
+      const $code = node.children.find(child => child.tagName === 'code');
+      addClass($code, 'language-typescript');
+      if (!$code.children[0].value.startsWith('\n')) {
+        $code.children.unshift({ type: 'text', value: '\n' });
+      }
+    }
+  });
+
+module.exports = [slug, [link]];
+
+export {};

compiler/api/processors/processDecorators.ts

@@ -0,0 +1,20 @@
+import { byId } from '../util/byId';
+
+module.exports = function processDecorators() {
+  return {
+    docTypes: [],
+    $runAfter: ['processing-docs'],
+    $runBefore: ['docs-processed'],
+    $process(docs: any[]) {
+      docs.forEach((doc, index) => {
+        if (
+          doc.fileInfo.baseName.endsWith('decorator') &&
+          (doc.docType === 'function' || doc.docType === 'const')
+        ) {
+          doc.docType = 'decorator';
+          doc.template = 'decorator.template.html';
+        }
+      });
+    }
+  };
+};

compiler/api/processors/processPackages.ts

@@ -19,6 +19,7 @@ module.exports = function processPackages() {
 
           if (doc.exports) {
             const publicExports = doc.exports.filter(doc => !doc.privateExport);
+            doc.modules = publicExports.filter(doc => doc.docType === 'decorator').sort(byId);
             doc.modules = publicExports.filter(doc => doc.docType === 'nestmodule').sort(byId);
             doc.classes = publicExports.filter(doc => doc.docType === 'class').sort(byId);
             doc.injectables = publicExports.filter(doc => doc.docType === 'injectable').sort(byId);

compiler/api/templates/decorator.template.html

@@ -0,0 +1,51 @@
+{% import "lib/githubLinks.html" as github -%}
+{% import "lib/memberHelpers.html" as memberHelper -%}
+{% import "lib/paramList.html" as params -%}
+{% extends 'export-base.template.html' %}
+
+{% block overview %}{% include "includes/decorator-overview.html" %}{% endblock %}
+{% block details %}
+{% include "includes/description.html" %}
+
+<section class="decorator-options">
+  {% if doc.members.length %}
+    <h2>Options</h2>
+    {% for option in doc.members %}
+    <a id="{$ option.anchor $}"></a>
+    <table class="is-full-width option-table">
+      <thead><tr><th>
+        <div class="with-github-links">
+          <h3>{$ option.name $}</h3>
+          {$ github.githubLinks(option, versionInfo) $}
+        </div>
+      </th></tr></thead>
+      <tbody>
+        <tr>
+          <td>
+            {% if option.shortDescription %}{$ option.shortDescription | marked $}{% endif %}
+          </td>
+        </tr>
+        <tr>
+          <td>
+            <code-example language="ts" hideCopy="true" class="no-box api-heading">
+            {$ option.name $}: {$ option.type | escape $}
+            </code-example>
+          </td>
+        </tr>
+        <tr>
+          <td>
+            {%- if option.description %}
+            {$ option.description | marked({ h3: 'h4' }) $}
+            {% endif %}
+
+            {%- if option.usageNotes %}
+            {$ option.usageNotes | marked({ h3: 'h4' }) $}
+            {% endif %}
+          </td>
+        </tr>
+      </tbody>
+    </table>
+    {% endfor %}
+  {% endif %}
+</section>
+{% endblock %}

compiler/api/templates/includes/decorator-overview.html

@@ -0,0 +1,33 @@
+{% import "lib/descendants.html" as descendants -%}
+
+{% macro renderOptionsTable(doc) %}
+<table class="is-full-width list-table option-overview">
+  <thead>
+    <tr><th>Option</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+  {%- for option in doc.members %}
+    <tr class="option">
+      <td>
+        <a class="code-anchor" href="{$ doc.path $}#{$ option.anchor | urlencode $}">
+          <code>{$ option.name $}</code>
+        </a>
+      </td>
+      <td>{$ option.shortDescription | marked $}</td>
+    </tr>
+    {% endfor -%}
+  </tbody>
+</table>
+
+{% for ancestor in doc.extendsClauses %}{% if ancestor.doc %}
+<h3 class="no-toc">Inherited from <a class="code-anchor" href="{$ ancestor.doc.path $}">{$ ancestor.doc.name $}</a> decorator</h3>
+{$ renderOptionsTable(ancestor.doc) $}
+{% endif %}{% endfor %}
+{% endmacro %}
+
+{% if doc.members.length %}
+<section class="decorator-overview">
+  {$ renderOptionsTable(doc) $}
+  {$ descendants.renderDescendants(doc, 'decorator', 'Subclasses') $}
+</section>
+{% endif %}