From e75f0cee18d92c8d27462cbaa6606e6c3d52b306 Mon Sep 17 00:00:00 2001
From: Pete Bacon Darwin <pete@bacondarwin.com>
Date: Fri, 23 Feb 2018 13:45:38 +0000
Subject: [PATCH] build(aio): deprecate `@howToUse` and `@whatItDoes` tags
 (#22401)

See https://github.com/angular/angular/issues/22135#issuecomment-367632372

PR Close #22401
---
 .../angular-api-package/tag-defs/howToUse.js          | 11 +++++++++--
 .../angular-api-package/tag-defs/whatItDoes.js        | 11 +++++++++--
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/aio/tools/transforms/angular-api-package/tag-defs/howToUse.js b/aio/tools/transforms/angular-api-package/tag-defs/howToUse.js
index f6073bb87a..aa5f3a2974 100644
--- a/aio/tools/transforms/angular-api-package/tag-defs/howToUse.js
+++ b/aio/tools/transforms/angular-api-package/tag-defs/howToUse.js
@@ -1,3 +1,10 @@
-module.exports = function() {
-  return {name: 'howToUse'};
+module.exports = function(log, createDocMessage) {
+  return {
+    name: 'howToUse',
+    transforms(doc, tag, value) {
+      log.warn(createDocMessage('Deprecated `@howToUse` tag found', doc));
+      log.warn('PLEASE FIX by renaming to `@usageNotes.');
+      return value;
+    }
+  };
 };
diff --git a/aio/tools/transforms/angular-api-package/tag-defs/whatItDoes.js b/aio/tools/transforms/angular-api-package/tag-defs/whatItDoes.js
index f11bb62a18..86715c6a5b 100644
--- a/aio/tools/transforms/angular-api-package/tag-defs/whatItDoes.js
+++ b/aio/tools/transforms/angular-api-package/tag-defs/whatItDoes.js
@@ -1,3 +1,10 @@
-module.exports = function() {
-  return {name: 'whatItDoes'};
+module.exports = function(log, createDocMessage) {
+  return {
+    name: 'whatItDoes',
+    transforms(doc, tag, value) {
+      log.warn(createDocMessage('Deprecated `@whatItDoes` tag found', doc));
+      log.warn('PLEASE FIX by adding the content of this tag as the first paragraph of the `@description` tag.');
+      return value;
+    }
+  };
 };