From 4168c946c6ce9300896337e2bd3b771026907be9 Mon Sep 17 00:00:00 2001
From: Pete Bacon Darwin <pete@bacondarwin.com>
Date: Wed, 16 May 2018 17:51:35 +0100
Subject: [PATCH] build(aio): add content rule to prevent usageNotes in
 non-export API docs (#24000)

This commit also factors out `API_CONTAINED_DOC_TYPES` to be used by
both `filterContainedDocs` and `addAllowedPropertiesRules`.

PR Close #24000
---
 .../transforms/angular-api-package/index.js   | 59 ++++++++++++++++++-
 1 file changed, 57 insertions(+), 2 deletions(-)

diff --git a/aio/tools/transforms/angular-api-package/index.js b/aio/tools/transforms/angular-api-package/index.js
index 6eef84a819..0ac6a3dc68 100644
--- a/aio/tools/transforms/angular-api-package/index.js
+++ b/aio/tools/transforms/angular-api-package/index.js
@@ -42,12 +42,19 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
     return EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe', 'module']);
   })
 
+  /**
+   * These are the doc types that are contained within other docs
+   */
+  .factory(function API_CONTAINED_DOC_TYPES() {
+    return ['member', 'function-overload', 'get-accessor-info', 'set-accessor-info', 'parameter'];
+  })
+
   /**
    * These are the doc types that are API docs, including ones that will be merged into container docs,
    * such as members and overloads.
    */
-  .factory(function API_DOC_TYPES(API_DOC_TYPES_TO_RENDER) {
-    return API_DOC_TYPES_TO_RENDER.concat(['member', 'function-overload']);
+  .factory(function API_DOC_TYPES(API_DOC_TYPES_TO_RENDER, API_CONTAINED_DOC_TYPES) {
+    return API_DOC_TYPES_TO_RENDER.concat(API_CONTAINED_DOC_TYPES);
   })
 
   // Where do we get the source files?
@@ -155,6 +162,16 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
     });
   })
 
+  .config(function(filterContainedDocs, API_CONTAINED_DOC_TYPES) {
+    filterContainedDocs.docTypes = API_CONTAINED_DOC_TYPES;
+  })
+
+  .config(function(checkContentRules, EXPORT_DOC_TYPES, API_CONTAINED_DOC_TYPES) {
+    addMinLengthRules(checkContentRules);
+    addHeadingRules(checkContentRules, EXPORT_DOC_TYPES);
+    addAllowedPropertiesRules(checkContentRules, API_CONTAINED_DOC_TYPES);
+  })
+
   .config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc) {
 
     const API_SEGMENT = 'api';
@@ -188,3 +205,41 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
     autoLinkCode.docTypes = API_DOC_TYPES;
     autoLinkCode.codeElements = ['code', 'code-example', 'code-pane'];
   });
+
+
+function addMinLengthRules(checkContentRules) {
+  const createMinLengthRule = require('./content-rules/minLength');
+  const paramRuleSet = checkContentRules.docTypeRules['parameter'] = checkContentRules.docTypeRules['parameter'] || {};
+  const paramRules = paramRuleSet['name'] = paramRuleSet['name'] || [];
+  paramRules.push(createMinLengthRule());
+}
+
+function addHeadingRules(checkContentRules, EXPORT_DOC_TYPES) {
+  const createNoMarkdownHeadingsRule = require('./content-rules/noMarkdownHeadings');
+  const noMarkdownHeadings = createNoMarkdownHeadingsRule();
+  const allowOnlyLevel3Headings = createNoMarkdownHeadingsRule(1, 2, '4,');
+  const DOC_TYPES_TO_CHECK = EXPORT_DOC_TYPES.concat(['member', 'overload-info']);
+  const PROPS_TO_CHECK = ['description', 'shortDescription'];
+
+  DOC_TYPES_TO_CHECK.forEach(docType => {
+    const ruleSet = checkContentRules.docTypeRules[docType] = checkContentRules.docTypeRules[docType] || {};
+    PROPS_TO_CHECK.forEach(prop => {
+      const rules = ruleSet[prop] = ruleSet[prop] || [];
+      rules.push(noMarkdownHeadings);
+    });
+    const rules = ruleSet['usageNotes'] = ruleSet['usageNotes'] || [];
+    rules.push(allowOnlyLevel3Headings);
+  });
+}
+
+function addAllowedPropertiesRules(checkContentRules, API_CONTAINED_DOC_TYPES) {
+  const PROPS_TO_DISALLOW = ['usageNotes'];
+
+  API_CONTAINED_DOC_TYPES.forEach(docType => {
+    const ruleSet = checkContentRules.docTypeRules[docType] = checkContentRules.docTypeRules[docType] || {};
+    PROPS_TO_DISALLOW.forEach(prop => {
+      const rules = ruleSet[prop] = ruleSet[prop] || [];
+      rules.push((doc, prop, value) => value && `Invalid property: "${prop}" is not allowed on "${doc.docType}" docs.`);
+    });
+  });
+}