From ddadb8e22cbacb04f5697de2fbdef4161deb727e Mon Sep 17 00:00:00 2001
From: Ben Lesh <ben@benlesh.com>
Date: Wed, 10 Apr 2019 13:45:26 -0700
Subject: [PATCH] refactor(ivy): Update @publicApi to @codeGenApi on ivy
 instructions (#29820)

- Removes `@publicApi` annotation from ivy instructions
- Adds new `@codeGenApi` annotation to ivy instructions
- Updates ts_api_guardian to support the new annotation properly

PR Close #29820
---
 packages/core/src/render3/definition.ts       | 14 +++++------
 packages/core/src/render3/di.ts               |  4 +--
 .../features/inherit_definition_feature.ts    |  2 +-
 .../render3/features/ng_onchanges_feature.ts  |  2 +-
 .../src/render3/features/providers_feature.ts |  2 +-
 packages/core/src/render3/i18n.ts             | 14 +++++------
 .../render3/instructions/alloc_host_vars.ts   |  2 +-
 .../src/render3/instructions/container.ts     |  8 +++---
 packages/core/src/render3/instructions/di.ts  |  4 +--
 .../core/src/render3/instructions/element.ts  | 10 ++++----
 .../render3/instructions/element_container.ts |  4 +--
 .../src/render3/instructions/embedded_view.ts |  6 ++---
 .../render3/instructions/get_current_view.ts  |  2 +-
 .../core/src/render3/instructions/listener.ts |  4 +--
 .../src/render3/instructions/next_context.ts  |  2 +-
 .../src/render3/instructions/projection.ts    |  4 +--
 .../core/src/render3/instructions/property.ts |  8 +++---
 .../instructions/property_interpolation.ts    | 18 ++++++-------
 .../core/src/render3/instructions/select.ts   |  2 +-
 .../core/src/render3/instructions/storage.ts  |  4 +--
 .../core/src/render3/instructions/styling.ts  | 20 +++++++--------
 .../core/src/render3/instructions/text.ts     |  4 +--
 .../core/src/render3/interfaces/definition.ts |  8 +++---
 packages/core/src/render3/pipe.ts             | 12 ++++-----
 packages/core/src/render3/pure_function.ts    | 20 +++++++--------
 packages/core/src/render3/query.ts            | 14 +++++------
 packages/core/src/render3/state.ts            | 12 ++++-----
 packages/core/src/render3/util/misc_utils.ts  |  6 ++---
 .../view_engine_compatibility_prebound.ts     |  2 +-
 tools/ts-api-guardian/lib/cli.ts              | 10 ++++----
 tools/ts-api-guardian/lib/serializer.ts       | 20 ++++++++-------
 tools/ts-api-guardian/test/unit_test.ts       | 25 ++++++++++++++-----
 32 files changed, 142 insertions(+), 127 deletions(-)

diff --git a/packages/core/src/render3/definition.ts b/packages/core/src/render3/definition.ts
index 5e8e62bde6..6cd7d1b06b 100644
--- a/packages/core/src/render3/definition.ts
+++ b/packages/core/src/render3/definition.ts
@@ -39,7 +39,7 @@ let _renderCompCount = 0;
  *   });
  * }
  * ```
- * @publicApi
+ * @codeGenApi
  */
 export function ΔdefineComponent<T>(componentDefinition: {
   /**
@@ -305,7 +305,7 @@ export function ΔdefineComponent<T>(componentDefinition: {
 }
 
 /**
- * @publicApi
+ * @codeGenApi
  */
 export function ΔsetComponentScope(
     type: ComponentType<any>, directives: Type<any>[], pipes: Type<any>[]): void {
@@ -332,7 +332,7 @@ export function extractPipeDef(type: PipeType<any>): PipeDef<any> {
 }
 
 /**
- * @publicApi
+ * @codeGenApi
  */
 export function ΔdefineNgModule<T>(def: {
   /** Token representing the module. Used by DI. */
@@ -376,7 +376,7 @@ export function ΔdefineNgModule<T>(def: {
  * marked pure to tree-shake it from the bundle, allowing for all referenced declarations
  * to become eligible for tree-shaking as well.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔsetNgModuleScope(type: any, scope: {
   /** List of components, directives, and pipes declared by this module. */
@@ -488,7 +488,7 @@ function invertObject<T>(
  *
  * @param baseDefinition The base definition parameters
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔdefineBase<T>(baseDefinition: {
   /**
@@ -570,7 +570,7 @@ export function ΔdefineBase<T>(baseDefinition: {
  * }
  * ```
  *
- * @publicApi
+ * @codeGenApi
  */
 export const ΔdefineDirective = ΔdefineComponent as any as<T>(directiveDefinition: {
   /**
@@ -688,7 +688,7 @@ export const ΔdefineDirective = ΔdefineComponent as any as<T>(directiveDefinit
  * ```
  * @param pipeDef Pipe definition generated by the compiler
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔdefinePipe<T>(pipeDef: {
   /** Name of the pipe. Used for matching pipes in template to pipe defs. */
diff --git a/packages/core/src/render3/di.ts b/packages/core/src/render3/di.ts
index 170c58680a..903fb65ee5 100644
--- a/packages/core/src/render3/di.ts
+++ b/packages/core/src/render3/di.ts
@@ -635,7 +635,7 @@ export class NodeInjector implements Injector {
 }
 
 /**
- * @publicApi
+ * @codeGenApi
  */
 export function ΔgetFactoryOf<T>(type: Type<any>): ((type: Type<T>| null) => T)|null {
   const typeAny = type as any;
@@ -648,7 +648,7 @@ export function ΔgetFactoryOf<T>(type: Type<any>): ((type: Type<T>| null) => T)
 }
 
 /**
- * @publicApi
+ * @codeGenApi
  */
 export function ΔgetInheritedFactory<T>(type: Type<any>): (type: Type<T>) => T {
   const proto = Object.getPrototypeOf(type.prototype).constructor as Type<any>;
diff --git a/packages/core/src/render3/features/inherit_definition_feature.ts b/packages/core/src/render3/features/inherit_definition_feature.ts
index 26e920fc7a..23cb66ec7a 100644
--- a/packages/core/src/render3/features/inherit_definition_feature.ts
+++ b/packages/core/src/render3/features/inherit_definition_feature.ts
@@ -24,7 +24,7 @@ function getSuperType(type: Type<any>): Type<any>&
  * Merges the definition from a super class to a sub class.
  * @param definition The definition that is a SubClass of another directive of component
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔInheritDefinitionFeature(definition: DirectiveDef<any>| ComponentDef<any>): void {
   let superType = getSuperType(definition.type);
diff --git a/packages/core/src/render3/features/ng_onchanges_feature.ts b/packages/core/src/render3/features/ng_onchanges_feature.ts
index 95c9d49ce9..a237afe9ea 100644
--- a/packages/core/src/render3/features/ng_onchanges_feature.ts
+++ b/packages/core/src/render3/features/ng_onchanges_feature.ts
@@ -39,7 +39,7 @@ type OnChangesExpando = OnChanges & {
  * });
  * ```
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔNgOnChangesFeature<T>(): DirectiveDefFeature {
   // This option ensures that the ngOnChanges lifecycle hook will be inherited
diff --git a/packages/core/src/render3/features/providers_feature.ts b/packages/core/src/render3/features/providers_feature.ts
index 0fbdea8b3b..df6223dcf2 100644
--- a/packages/core/src/render3/features/providers_feature.ts
+++ b/packages/core/src/render3/features/providers_feature.ts
@@ -37,7 +37,7 @@ import {DirectiveDef} from '../interfaces/definition';
  *
  * @param definition
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔProvidersFeature<T>(providers: Provider[], viewProviders: Provider[] = []) {
   return (definition: DirectiveDef<T>) => {
diff --git a/packages/core/src/render3/i18n.ts b/packages/core/src/render3/i18n.ts
index 53e75777a4..1a85d25f52 100644
--- a/packages/core/src/render3/i18n.ts
+++ b/packages/core/src/render3/i18n.ts
@@ -347,7 +347,7 @@ const parentIndexStack: number[] = [];
  * @param message The translation message.
  * @param subTemplateIndex Optional sub-template index in the `message`.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δi18nStart(index: number, message: string, subTemplateIndex?: number): void {
   const tView = getLView()[TVIEW];
@@ -534,7 +534,7 @@ function appendI18nNode(tNode: TNode, parentTNode: TNode, previousTNode: TNode |
  *
  * @returns Transformed string that can be consumed by i18nStart instruction
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δi18nPostprocess(
     message: string, replacements: {[key: string]: (string | string[])} = {}): string {
@@ -630,7 +630,7 @@ export function Δi18nPostprocess(
  * Translates a translation block marked by `i18nStart` and `i18nEnd`. It inserts the text/ICU nodes
  * into the render tree, moves the placeholder nodes and removes the deleted nodes.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δi18nEnd(): void {
   const tView = getLView()[TVIEW];
@@ -919,7 +919,7 @@ function removeNode(index: number, viewData: LView) {
  * @param message The translation message.
  * @param subTemplateIndex Optional sub-template index in the `message`.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δi18n(index: number, message: string, subTemplateIndex?: number): void {
   Δi18nStart(index, message, subTemplateIndex);
@@ -932,7 +932,7 @@ export function Δi18n(index: number, message: string, subTemplateIndex?: number
  * @param index A unique index in the static block
  * @param values
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δi18nAttributes(index: number, values: string[]): void {
   const tView = getLView()[TVIEW];
@@ -984,7 +984,7 @@ let shiftsCounter = 0;
  *
  * @param expression The binding's new value or NO_CHANGE
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δi18nExp<T>(expression: T | NO_CHANGE): void {
   if (expression !== NO_CHANGE) {
@@ -999,7 +999,7 @@ export function Δi18nExp<T>(expression: T | NO_CHANGE): void {
  * @param index Index of either {@link i18nStart} (translation block) or {@link i18nAttributes}
  * (i18n attribute) on which it should update the content.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δi18nApply(index: number) {
   if (shiftsCounter) {
diff --git a/packages/core/src/render3/instructions/alloc_host_vars.ts b/packages/core/src/render3/instructions/alloc_host_vars.ts
index fdc2f2a554..2e12f1a9e9 100644
--- a/packages/core/src/render3/instructions/alloc_host_vars.ts
+++ b/packages/core/src/render3/instructions/alloc_host_vars.ts
@@ -17,7 +17,7 @@ import {NO_CHANGE} from '../tokens';
  *
  * @param count Amount of vars to be allocated
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔallocHostVars(count: number): void {
   const lView = getLView();
diff --git a/packages/core/src/render3/instructions/container.ts b/packages/core/src/render3/instructions/container.ts
index f80df62651..6cac4418c7 100644
--- a/packages/core/src/render3/instructions/container.ts
+++ b/packages/core/src/render3/instructions/container.ts
@@ -28,7 +28,7 @@ import {addToViewTree, createDirectivesAndLocals, createLContainer, createNodeAt
  *
  * @param index The index of the container in the data array
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δcontainer(index: number): void {
   const tNode = containerInternal(index, null, null);
@@ -57,7 +57,7 @@ export function Δcontainer(index: number): void {
  * @param localRefExtractor A function which extracts local-refs values from the template.
  *        Defaults to the current element associated with the local-ref.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δtemplate(
     index: number, templateFn: ComponentTemplate<any>| null, consts: number, vars: number,
@@ -85,7 +85,7 @@ export function Δtemplate(
  *
  * @param index The index of the container in the data array
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔcontainerRefreshStart(index: number): void {
   const lView = getLView();
@@ -108,7 +108,7 @@ export function ΔcontainerRefreshStart(index: number): void {
  *
  * Marking the end of LContainer is the time when to child views get inserted or removed.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔcontainerRefreshEnd(): void {
   let previousOrParentTNode = getPreviousOrParentTNode();
diff --git a/packages/core/src/render3/instructions/di.ts b/packages/core/src/render3/instructions/di.ts
index 40f7ec6a8a..7685d1e0d7 100644
--- a/packages/core/src/render3/instructions/di.ts
+++ b/packages/core/src/render3/instructions/di.ts
@@ -33,7 +33,7 @@ import {getLView, getPreviousOrParentTNode} from '../state';
  * @param flags Injection flags
  * @returns the value from the injector or `null` when not found
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔdirectiveInject<T>(token: Type<T>| InjectionToken<T>): T;
 export function ΔdirectiveInject<T>(token: Type<T>| InjectionToken<T>, flags: InjectFlags): T;
@@ -48,7 +48,7 @@ export function ΔdirectiveInject<T>(
 /**
  * Facade for the attribute injection from DI.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔinjectAttribute(attrNameToInject: string): string|null {
   return injectAttributeImpl(getPreviousOrParentTNode(), attrNameToInject);
diff --git a/packages/core/src/render3/instructions/element.ts b/packages/core/src/render3/instructions/element.ts
index a7aeb81a20..016d8b98df 100644
--- a/packages/core/src/render3/instructions/element.ts
+++ b/packages/core/src/render3/instructions/element.ts
@@ -42,7 +42,7 @@ import {getActiveDirectiveStylingIndex} from './styling';
  * hold an attribute name and elements with an odd index hold an attribute value, ex.:
  * ['id', 'warning5', 'class', 'alert']
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementStart(
     index: number, name: string, attrs?: TAttributes | null, localRefs?: string[] | null): void {
@@ -127,7 +127,7 @@ export function ΔelementStart(
 /**
  * Mark the end of the element.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementEnd(): void {
   let previousOrParentTNode = getPreviousOrParentTNode();
@@ -179,7 +179,7 @@ export function ΔelementEnd(): void {
  *              element on creation. Use [AttributeMarker] to denote the meaning of this array.
  * @param localRefs A set of local reference bindings on the element.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δelement(
     index: number, name: string, attrs?: TAttributes | null, localRefs?: string[] | null): void {
@@ -198,7 +198,7 @@ export function Δelement(
  * @param sanitizer An optional function used to sanitize the value.
  * @param namespace Optional namespace to use when setting the attribute.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementAttribute(
     index: number, name: string, value: any, sanitizer?: SanitizerFn | null,
@@ -266,7 +266,7 @@ export function ΔelementAttribute(
  * @param attrs An array of static values (attributes, classes and styles) with the correct marker
  * values.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementHostAttrs(attrs: TAttributes) {
   const hostElementIndex = getSelectedIndex();
diff --git a/packages/core/src/render3/instructions/element_container.ts b/packages/core/src/render3/instructions/element_container.ts
index 77f4b4ccf1..15002fc6b4 100644
--- a/packages/core/src/render3/instructions/element_container.ts
+++ b/packages/core/src/render3/instructions/element_container.ts
@@ -29,7 +29,7 @@ import {createDirectivesAndLocals, createNodeAtIndex, executeContentQueries, set
  * the DOM (as a comment node can't have attributes). Attributes are here only for directive
  * matching purposes and setting initial inputs of directives.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementContainerStart(
     index: number, attrs?: TAttributes | null, localRefs?: string[] | null): void {
@@ -70,7 +70,7 @@ export function ΔelementContainerStart(
 /**
  * Mark the end of the <ng-container>.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementContainerEnd(): void {
   let previousOrParentTNode = getPreviousOrParentTNode();
diff --git a/packages/core/src/render3/instructions/embedded_view.ts b/packages/core/src/render3/instructions/embedded_view.ts
index f1f1f54047..80c11d1efa 100644
--- a/packages/core/src/render3/instructions/embedded_view.ts
+++ b/packages/core/src/render3/instructions/embedded_view.ts
@@ -23,8 +23,8 @@ import {assignTViewNodeToLView, createLView, createTView, refreshDescendantViews
  *
  * @param viewBlockId The ID of this view
  * @return boolean Whether or not this view is in creation mode
- * 
- * @publicApi
+ *
+ * @codeGenApi
  */
 export function ΔembeddedViewStart(viewBlockId: number, consts: number, vars: number): RenderFlags {
   const lView = getLView();
@@ -127,7 +127,7 @@ function scanForView(lContainer: LContainer, startIdx: number, viewBlockId: numb
 /**
  * Marks the end of an embedded view.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔembeddedViewEnd(): void {
   const lView = getLView();
diff --git a/packages/core/src/render3/instructions/get_current_view.ts b/packages/core/src/render3/instructions/get_current_view.ts
index 04de91ee22..f477a1e569 100644
--- a/packages/core/src/render3/instructions/get_current_view.ts
+++ b/packages/core/src/render3/instructions/get_current_view.ts
@@ -15,7 +15,7 @@ import {getLView} from '../state';
  * of the current view and restore it when listeners are invoked. This allows
  * walking the declaration view tree in listeners to get vars from parent views.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔgetCurrentView(): OpaqueViewState {
   return getLView() as any as OpaqueViewState;
diff --git a/packages/core/src/render3/instructions/listener.ts b/packages/core/src/render3/instructions/listener.ts
index 4cd9fe1a3c..a8c18c1558 100644
--- a/packages/core/src/render3/instructions/listener.ts
+++ b/packages/core/src/render3/instructions/listener.ts
@@ -29,7 +29,7 @@ import {BindingDirection, generatePropertyAliases, getCleanup, handleError, load
  * @param eventTargetResolver Function that returns global target information in case this listener
  * should be attached to a global object like window, document or body
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δlistener(
     eventName: string, listenerFn: (e?: any) => any, useCapture = false,
@@ -56,7 +56,7 @@ export function Δlistener(
 * @param eventTargetResolver Function that returns global target information in case this listener
 * should be attached to a global object like window, document or body
  *
- * @publicApi
+ * @codeGenApi
 */
 export function ΔcomponentHostSyntheticListener<T>(
     eventName: string, listenerFn: (e?: any) => any, useCapture = false,
diff --git a/packages/core/src/render3/instructions/next_context.ts b/packages/core/src/render3/instructions/next_context.ts
index a4af7bba2d..3994247692 100644
--- a/packages/core/src/render3/instructions/next_context.ts
+++ b/packages/core/src/render3/instructions/next_context.ts
@@ -17,7 +17,7 @@ import {nextContextImpl} from '../state';
  * @param level The relative level of the view from which to grab context compared to contextVewData
  * @returns context
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔnextContext<T = any>(level: number = 1): T {
   return nextContextImpl(level);
diff --git a/packages/core/src/render3/instructions/projection.ts b/packages/core/src/render3/instructions/projection.ts
index 18c1a9be6e..1237a3b346 100644
--- a/packages/core/src/render3/instructions/projection.ts
+++ b/packages/core/src/render3/instructions/projection.ts
@@ -37,7 +37,7 @@ import {createNodeAtIndex} from './shared';
  * @param selectors A collection of parsed CSS selectors
  * @param rawSelectors A collection of CSS selectors in the raw, un-parsed form
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔprojectionDef(selectors?: CssSelectorList[]): void {
   const componentNode = findComponentView(getLView())[T_HOST] as TElementNode;
@@ -76,7 +76,7 @@ export function ΔprojectionDef(selectors?: CssSelectorList[]): void {
  *        - 0 when the selector is `*` (or unspecified as this is the default value),
  *        - 1 based index of the selector from the {@link projectionDef}
   *
- * @publicApi
+ * @codeGenApi
 */
 export function Δprojection(
     nodeIndex: number, selectorIndex: number = 0, attrs?: TAttributes): void {
diff --git a/packages/core/src/render3/instructions/property.ts b/packages/core/src/render3/instructions/property.ts
index 4e6dceff75..8cd388009d 100644
--- a/packages/core/src/render3/instructions/property.ts
+++ b/packages/core/src/render3/instructions/property.ts
@@ -32,7 +32,7 @@ import {TsickleIssue1009, elementPropertyInternal, loadComponentRenderer, storeB
  * @returns This function returns itself so that it may be chained
  * (e.g. `property('name', ctx.name)('title', ctx.title)`)
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δproperty<T>(
     propName: string, value: T, sanitizer?: SanitizerFn | null,
@@ -48,7 +48,7 @@ export function Δproperty<T>(
  *
  * @param value Value to diff
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δbind<T>(value: T): T|NO_CHANGE {
   const lView = getLView();
@@ -73,7 +73,7 @@ export function Δbind<T>(value: T): T|NO_CHANGE {
 * @param nativeOnly Whether or not we should only set native properties and skip input check
 * (this is necessary for host property bindings)
  *
- * @publicApi
+ * @codeGenApi
 */
 export function ΔelementProperty<T>(
     index: number, propName: string, value: T | NO_CHANGE, sanitizer?: SanitizerFn | null,
@@ -102,7 +102,7 @@ export function ΔelementProperty<T>(
  * @param nativeOnly Whether or not we should only set native properties and skip input check
  * (this is necessary for host property bindings)
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔcomponentHostSyntheticProperty<T>(
     index: number, propName: string, value: T | NO_CHANGE, sanitizer?: SanitizerFn | null,
diff --git a/packages/core/src/render3/instructions/property_interpolation.ts b/packages/core/src/render3/instructions/property_interpolation.ts
index 9e6aeca356..d0dafd10b0 100644
--- a/packages/core/src/render3/instructions/property_interpolation.ts
+++ b/packages/core/src/render3/instructions/property_interpolation.ts
@@ -27,7 +27,7 @@ import {TsickleIssue1009, elementPropertyInternal, storeBindingMetadata} from '.
  *
  * Returns the concatenated string when any of the arguments changes, `NO_CHANGE` otherwise.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔinterpolationV(values: any[]): string|NO_CHANGE {
   ngDevMode && assertLessThan(2, values.length, 'should have at least 3 values');
@@ -72,7 +72,7 @@ export function ΔinterpolationV(values: any[]): string|NO_CHANGE {
  * @param v0 value checked for change.
  * @param suffix static value used for concatenation only.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δinterpolation1(prefix: string, v0: any, suffix: string): string|NO_CHANGE {
   const lView = getLView();
@@ -84,7 +84,7 @@ export function Δinterpolation1(prefix: string, v0: any, suffix: string): strin
 /**
  * Creates an interpolation binding with 2 expressions.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δinterpolation2(
     prefix: string, v0: any, i0: string, v1: any, suffix: string): string|NO_CHANGE {
@@ -105,7 +105,7 @@ export function Δinterpolation2(
 /**
  * Creates an interpolation binding with 3 expressions.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δinterpolation3(
     prefix: string, v0: any, i0: string, v1: any, i1: string, v2: any, suffix: string): string|
@@ -131,7 +131,7 @@ export function Δinterpolation3(
 /**
  * Create an interpolation binding with 4 expressions.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δinterpolation4(
     prefix: string, v0: any, i0: string, v1: any, i1: string, v2: any, i2: string, v3: any,
@@ -159,7 +159,7 @@ export function Δinterpolation4(
 /**
  * Creates an interpolation binding with 5 expressions.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δinterpolation5(
     prefix: string, v0: any, i0: string, v1: any, i1: string, v2: any, i2: string, v3: any,
@@ -189,7 +189,7 @@ export function Δinterpolation5(
 /**
  * Creates an interpolation binding with 6 expressions.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δinterpolation6(
     prefix: string, v0: any, i0: string, v1: any, i1: string, v2: any, i2: string, v3: any,
@@ -220,7 +220,7 @@ export function Δinterpolation6(
 /**
  * Creates an interpolation binding with 7 expressions.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δinterpolation7(
     prefix: string, v0: any, i0: string, v1: any, i1: string, v2: any, i2: string, v3: any,
@@ -254,7 +254,7 @@ export function Δinterpolation7(
 /**
  * Creates an interpolation binding with 8 expressions.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δinterpolation8(
     prefix: string, v0: any, i0: string, v1: any, i1: string, v2: any, i2: string, v3: any,
diff --git a/packages/core/src/render3/instructions/select.ts b/packages/core/src/render3/instructions/select.ts
index 91fdaaba43..1927723f41 100644
--- a/packages/core/src/render3/instructions/select.ts
+++ b/packages/core/src/render3/instructions/select.ts
@@ -29,7 +29,7 @@ import {getCheckNoChangesMode, getLView, setSelectedIndex} from '../state';
  * ```
  * @param index the index of the item to act on with the following instructions
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δselect(index: number): void {
   ngDevMode && assertGreaterThan(index, -1, 'Invalid index');
diff --git a/packages/core/src/render3/instructions/storage.ts b/packages/core/src/render3/instructions/storage.ts
index 5d89def67f..53c1944191 100644
--- a/packages/core/src/render3/instructions/storage.ts
+++ b/packages/core/src/render3/instructions/storage.ts
@@ -31,7 +31,7 @@ export function store<T>(index: number, value: T): void {
  *
  * @param index The index of the local ref in contextViewData.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δreference<T>(index: number) {
   const contextLView = getContextLView();
@@ -41,7 +41,7 @@ export function Δreference<T>(index: number) {
 /**
  * Retrieves a value from current `viewData`.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δload<T>(index: number): T {
   return loadInternal<T>(getLView(), index);
diff --git a/packages/core/src/render3/instructions/styling.ts b/packages/core/src/render3/instructions/styling.ts
index 9f5abf3ceb..cf0e5705c5 100644
--- a/packages/core/src/render3/instructions/styling.ts
+++ b/packages/core/src/render3/instructions/styling.ts
@@ -62,7 +62,7 @@ import {scheduleTick, setInputsForProperty} from './shared';
  * @param styleSanitizer An optional sanitizer function that will be used to sanitize any CSS
  *        style values that are applied to the element (during rendering).
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementStyling(
     classBindingNames?: string[] | null, styleBindingNames?: string[] | null,
@@ -104,7 +104,7 @@ export function ΔelementStyling(
  *        will not be used if the same property is assigned in another directive or
  *        on the element directly.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementHostStyling(
     classBindingNames?: string[] | null, styleBindingNames?: string[] | null,
@@ -164,7 +164,7 @@ function initElementStyling(
  * @param forceOverride Whether or not to update the styling value immediately
  *        (despite the other bindings possibly having priority)
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementStyleProp(
     index: number, styleIndex: number, value: string | number | String | PlayerFactory | null,
@@ -198,7 +198,7 @@ export function ΔelementStyleProp(
  * @param forceOverride Whether or not to update the styling value immediately
  *        (despite the other bindings possibly having priority)
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementHostStyleProp(
     styleIndex: number, value: string | number | String | PlayerFactory | null,
@@ -251,7 +251,7 @@ function resolveStylePropValue(
  * @param forceOverride Whether or not this value will be applied regardless
  *        of where it is being set within the styling priority structure.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementClassProp(
     index: number, classIndex: number, value: boolean | PlayerFactory,
@@ -281,7 +281,7 @@ export function ΔelementClassProp(
  * @param forceOverride Whether or not this value will be applied regardless
  *        of where it is being set within the stylings priority structure.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementHostClassProp(
     classIndex: number, value: boolean | PlayerFactory, forceOverride?: boolean): void {
@@ -324,7 +324,7 @@ function booleanOrNull(value: any): boolean|null {
  *        Any missing styles (that have already been applied to the element beforehand) will be
  *        removed (unset) from the element's styling.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementStylingMap(
     index: number, classes: {[key: string]: any} | string | NO_CHANGE | null,
@@ -377,7 +377,7 @@ export function ΔelementStylingMap(
  *        Any missing styles (that have already been applied to the element beforehand) will be
  *        removed (unset) from the element's styling.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementHostStylingMap(
     classes: {[key: string]: any} | string | NO_CHANGE | null,
@@ -403,7 +403,7 @@ export function ΔelementHostStylingMap(
  *
  * @param index Index of the element's with which styling is associated.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementStylingApply(index: number): void {
   elementStylingApplyInternal(DEFAULT_TEMPLATE_DIRECTIVE_INDEX, index);
@@ -417,7 +417,7 @@ export function ΔelementStylingApply(index: number): void {
  * been run and will only apply styling to the host element if any
  * styling bindings have been updated.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔelementHostStylingApply(): void {
   elementStylingApplyInternal(getActiveDirectiveStylingIndex(), getSelectedIndex());
diff --git a/packages/core/src/render3/instructions/text.ts b/packages/core/src/render3/instructions/text.ts
index d0e28cbf1c..1792ed6f78 100644
--- a/packages/core/src/render3/instructions/text.ts
+++ b/packages/core/src/render3/instructions/text.ts
@@ -22,7 +22,7 @@ import {createNodeAtIndex} from './shared';
  * @param index Index of the node in the data array
  * @param value Value to write. This value will be stringified.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δtext(index: number, value?: any): void {
   const lView = getLView();
@@ -45,7 +45,7 @@ export function Δtext(index: number, value?: any): void {
  * @param index Index of the node in the data array.
  * @param value Stringified value to write.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔtextBinding<T>(index: number, value: T | NO_CHANGE): void {
   if (value !== NO_CHANGE) {
diff --git a/packages/core/src/render3/interfaces/definition.ts b/packages/core/src/render3/interfaces/definition.ts
index aba530aeee..29a8940f52 100644
--- a/packages/core/src/render3/interfaces/definition.ts
+++ b/packages/core/src/render3/interfaces/definition.ts
@@ -86,7 +86,7 @@ export const enum DirectiveDefFlags {ContentQuery = 0b10}
 export interface PipeType<T> extends Type<T> { ngPipeDef: never; }
 
 /**
- * @publicApi
+ * @codeGenApi
  */
 export type ΔDirectiveDefWithMeta<
     T, Selector extends string, ExportAs extends string[], InputMap extends{[key: string]: string},
@@ -101,7 +101,7 @@ export type ΔDirectiveDefWithMeta<
  *
  * See: {@link defineBase}
  *
- * @publicApi
+ * @codeGenApi
  */
 export interface ΔBaseDef<T> {
   /**
@@ -200,7 +200,7 @@ export interface DirectiveDef<T> extends ΔBaseDef<T> {
 }
 
 /**
- * @publicApi
+ * @codeGenApi
  */
 export type ΔComponentDefWithMeta<
     T, Selector extends String, ExportAs extends string[], InputMap extends{[key: string]: string},
@@ -347,7 +347,7 @@ export interface PipeDef<T> {
 }
 
 /**
- * @publicApi
+ * @codeGenApi
  */
 export type ΔPipeDefWithMeta<T, Name extends string> = PipeDef<T>;
 
diff --git a/packages/core/src/render3/pipe.ts b/packages/core/src/render3/pipe.ts
index f4f1adb37b..10caa79a0e 100644
--- a/packages/core/src/render3/pipe.ts
+++ b/packages/core/src/render3/pipe.ts
@@ -25,7 +25,7 @@ import {NO_CHANGE} from './tokens';
  * @param pipeName The name of the pipe
  * @returns T the instance of the pipe.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function Δpipe(index: number, pipeName: string): any {
   const tView = getLView()[TVIEW];
@@ -79,7 +79,7 @@ function getPipeDef(name: string, registry: PipeDefList | null): PipeDef<any> {
  * @param slotOffset the offset in the reserved slot space
  * @param v1 1st argument to {@link PipeTransform#transform}.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpipeBind1(index: number, slotOffset: number, v1: any): any {
   const pipeInstance = Δload<PipeTransform>(index);
@@ -99,7 +99,7 @@ export function ΔpipeBind1(index: number, slotOffset: number, v1: any): any {
  * @param v1 1st argument to {@link PipeTransform#transform}.
  * @param v2 2nd argument to {@link PipeTransform#transform}.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpipeBind2(index: number, slotOffset: number, v1: any, v2: any): any {
   const pipeInstance = Δload<PipeTransform>(index);
@@ -120,7 +120,7 @@ export function ΔpipeBind2(index: number, slotOffset: number, v1: any, v2: any)
  * @param v2 2nd argument to {@link PipeTransform#transform}.
  * @param v3 4rd argument to {@link PipeTransform#transform}.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpipeBind3(index: number, slotOffset: number, v1: any, v2: any, v3: any): any {
   const pipeInstance = Δload<PipeTransform>(index);
@@ -142,7 +142,7 @@ export function ΔpipeBind3(index: number, slotOffset: number, v1: any, v2: any,
  * @param v3 3rd argument to {@link PipeTransform#transform}.
  * @param v4 4th argument to {@link PipeTransform#transform}.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpipeBind4(
     index: number, slotOffset: number, v1: any, v2: any, v3: any, v4: any): any {
@@ -163,7 +163,7 @@ export function ΔpipeBind4(
  * @param slotOffset the offset in the reserved slot space
  * @param values Array of arguments to pass to {@link PipeTransform#transform} method.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpipeBindV(index: number, slotOffset: number, values: any[]): any {
   const pipeInstance = Δload<PipeTransform>(index);
diff --git a/packages/core/src/render3/pure_function.ts b/packages/core/src/render3/pure_function.ts
index 849190df56..bd4f1cd255 100644
--- a/packages/core/src/render3/pure_function.ts
+++ b/packages/core/src/render3/pure_function.ts
@@ -38,7 +38,7 @@ import {getBindingRoot, getLView, isCreationMode} from './state';
  * @param thisArg Optional calling context of pureFn
  * @returns value
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpureFunction0<T>(slotOffset: number, pureFn: () => T, thisArg?: any): T {
   // TODO(kara): use bindingRoot instead of bindingStartIndex when implementing host bindings
@@ -59,7 +59,7 @@ export function ΔpureFunction0<T>(slotOffset: number, pureFn: () => T, thisArg?
  * @param thisArg Optional calling context of pureFn
  * @returns Updated or cached value
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpureFunction1(
     slotOffset: number, pureFn: (v: any) => any, exp: any, thisArg?: any): any {
@@ -82,7 +82,7 @@ export function ΔpureFunction1(
  * @param thisArg Optional calling context of pureFn
  * @returns Updated or cached value
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpureFunction2(
     slotOffset: number, pureFn: (v1: any, v2: any) => any, exp1: any, exp2: any,
@@ -109,7 +109,7 @@ export function ΔpureFunction2(
  * @param thisArg Optional calling context of pureFn
  * @returns Updated or cached value
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpureFunction3(
     slotOffset: number, pureFn: (v1: any, v2: any, v3: any) => any, exp1: any, exp2: any, exp3: any,
@@ -137,7 +137,7 @@ export function ΔpureFunction3(
  * @param thisArg Optional calling context of pureFn
  * @returns Updated or cached value
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpureFunction4(
     slotOffset: number, pureFn: (v1: any, v2: any, v3: any, v4: any) => any, exp1: any, exp2: any,
@@ -166,7 +166,7 @@ export function ΔpureFunction4(
  * @param thisArg Optional calling context of pureFn
  * @returns Updated or cached value
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpureFunction5(
     slotOffset: number, pureFn: (v1: any, v2: any, v3: any, v4: any, v5: any) => any, exp1: any,
@@ -197,7 +197,7 @@ export function ΔpureFunction5(
  * @param thisArg Optional calling context of pureFn
  * @returns Updated or cached value
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpureFunction6(
     slotOffset: number, pureFn: (v1: any, v2: any, v3: any, v4: any, v5: any, v6: any) => any,
@@ -230,7 +230,7 @@ export function ΔpureFunction6(
  * @param thisArg Optional calling context of pureFn
  * @returns Updated or cached value
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpureFunction7(
     slotOffset: number,
@@ -265,7 +265,7 @@ export function ΔpureFunction7(
  * @param thisArg Optional calling context of pureFn
  * @returns Updated or cached value
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpureFunction8(
     slotOffset: number,
@@ -297,7 +297,7 @@ export function ΔpureFunction8(
  * @param thisArg Optional calling context of pureFn
  * @returns Updated or cached value
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔpureFunctionV(
     slotOffset: number, pureFn: (...v: any[]) => any, exps: any[], thisArg?: any): any {
diff --git a/packages/core/src/render3/query.ts b/packages/core/src/render3/query.ts
index 2cfd097880..3c7b948587 100644
--- a/packages/core/src/render3/query.ts
+++ b/packages/core/src/render3/query.ts
@@ -370,7 +370,7 @@ export function query<T>(
  * @returns `true` if a query got dirty during change detection or if this is a static query
  * resolving in creation mode, `false` otherwise.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔqueryRefresh(queryList: QueryList<any>): boolean {
   const queryListImpl = (queryList as any as QueryList_<any>);
@@ -392,7 +392,7 @@ export function ΔqueryRefresh(queryList: QueryList<any>): boolean {
  * @param descend Whether or not to descend into children
  * @param read What to save in the query
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔstaticViewQuery<T>(
     // TODO(FW-486): "read" should be an AbstractType
@@ -413,7 +413,7 @@ export function ΔstaticViewQuery<T>(
  * @param read What to save in the query
  * @returns QueryList<T>
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔviewQuery<T>(
     // TODO(FW-486): "read" should be an AbstractType
@@ -433,7 +433,7 @@ export function ΔviewQuery<T>(
 /**
  * Loads current View Query and moves the pointer/index to the next View Query in LView.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔloadViewQuery<T>(): T {
   const index = getCurrentQueryIndex();
@@ -451,7 +451,7 @@ export function ΔloadViewQuery<T>(): T {
  * @param read What to save in the query
  * @returns QueryList<T>
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔcontentQuery<T>(
     directiveIndex: number, predicate: Type<any>| string[], descend: boolean,
@@ -482,7 +482,7 @@ export function ΔcontentQuery<T>(
  * @param read What to save in the query
  * @returns QueryList<T>
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔstaticContentQuery<T>(
     directiveIndex: number, predicate: Type<any>| string[], descend: boolean,
@@ -498,7 +498,7 @@ export function ΔstaticContentQuery<T>(
 
 /**
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔloadContentQuery<T>(): QueryList<T> {
   const lView = getLView();
diff --git a/packages/core/src/render3/state.ts b/packages/core/src/render3/state.ts
index 2addeab633..3d289451b7 100644
--- a/packages/core/src/render3/state.ts
+++ b/packages/core/src/render3/state.ts
@@ -90,7 +90,7 @@ export function getBindingsEnabled(): boolean {
  * </div>
  * ```
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔenableBindings(): void {
   bindingsEnabled = true;
@@ -113,7 +113,7 @@ export function ΔenableBindings(): void {
  * </div>
  * ```
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔdisableBindings(): void {
   bindingsEnabled = false;
@@ -267,7 +267,7 @@ export function getActiveDirectiveSuperClassDepth() {
  *
  * @param viewToRestore The OpaqueViewState instance to restore.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔrestoreView(viewToRestore: OpaqueViewState) {
   contextLView = viewToRestore as any as LView;
@@ -490,7 +490,7 @@ let _currentNamespace: string|null = null;
 /**
  * Sets the namespace used to create elements to `'http://www.w3.org/2000/svg'` in global state.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔnamespaceSVG() {
   _currentNamespace = 'http://www.w3.org/2000/svg';
@@ -499,7 +499,7 @@ export function ΔnamespaceSVG() {
 /**
  * Sets the namespace used to create elements to `'http://www.w3.org/1998/MathML/'` in global state.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔnamespaceMathML() {
   _currentNamespace = 'http://www.w3.org/1998/MathML/';
@@ -509,7 +509,7 @@ export function ΔnamespaceMathML() {
  * Sets the namespace used to create elements no `null`, which forces element creation to use
  * `createElement` rather than `createElementNS`.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔnamespaceHTML() {
   _currentNamespace = null;
diff --git a/packages/core/src/render3/util/misc_utils.ts b/packages/core/src/render3/util/misc_utils.ts
index 35988308eb..7fa449e622 100644
--- a/packages/core/src/render3/util/misc_utils.ts
+++ b/packages/core/src/render3/util/misc_utils.ts
@@ -43,7 +43,7 @@ export const defaultScheduler =
 
 /**
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔresolveWindow(element: RElement & {ownerDocument: Document}) {
   return {name: 'window', target: element.ownerDocument.defaultView};
@@ -51,7 +51,7 @@ export function ΔresolveWindow(element: RElement & {ownerDocument: Document}) {
 
 /**
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔresolveDocument(element: RElement & {ownerDocument: Document}) {
   return {name: 'document', target: element.ownerDocument};
@@ -59,7 +59,7 @@ export function ΔresolveDocument(element: RElement & {ownerDocument: Document})
 
 /**
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔresolveBody(element: RElement & {ownerDocument: Document}) {
   return {name: 'body', target: element.ownerDocument.body};
diff --git a/packages/core/src/render3/view_engine_compatibility_prebound.ts b/packages/core/src/render3/view_engine_compatibility_prebound.ts
index 216fd6c3a4..a2cdbc706c 100644
--- a/packages/core/src/render3/view_engine_compatibility_prebound.ts
+++ b/packages/core/src/render3/view_engine_compatibility_prebound.ts
@@ -20,7 +20,7 @@ import {createTemplateRef} from './view_engine_compatibility';
  * Retrieves `TemplateRef` instance from `Injector` when a local reference is placed on the
  * `<ng-template>` element.
  *
- * @publicApi
+ * @codeGenApi
  */
 export function ΔtemplateRefExtractor(tNode: TNode, currentView: LView) {
   return createTemplateRef(ViewEngine_TemplateRef, ViewEngine_ElementRef, tNode, currentView);
diff --git a/tools/ts-api-guardian/lib/cli.ts b/tools/ts-api-guardian/lib/cli.ts
index e2d6153338..55720010ff 100644
--- a/tools/ts-api-guardian/lib/cli.ts
+++ b/tools/ts-api-guardian/lib/cli.ts
@@ -30,18 +30,18 @@ export function startCli() {
   // Angular project tag rules unless specified explicitly through a given option.
   if (argv['useAngularTagRules']) {
     options.exportTags = {
-      required: ['publicApi'],
+      requireAtLeastOne: ['publicApi', 'codeGenApi'],
       banned: ['experimental'],
       toCopy: ['deprecated']
     };
     options.memberTags = {
-      required: [],
-      banned: ['experimental', 'publicApi'],
+      requireAtLeastOne: [],
+      banned: ['experimental', 'publicApi', 'codeGenApi'],
       toCopy: ['deprecated']
     };
     options.paramTags = {
-      required: [],
-      banned: ['experimental', 'publicApi'],
+      requireAtLeastOne: [],
+      banned: ['experimental', 'publicApi', 'codeGenApi'],
       toCopy: ['deprecated']
     };
   }
diff --git a/tools/ts-api-guardian/lib/serializer.ts b/tools/ts-api-guardian/lib/serializer.ts
index 3aa1dbe7b5..1f4402ad48 100644
--- a/tools/ts-api-guardian/lib/serializer.ts
+++ b/tools/ts-api-guardian/lib/serializer.ts
@@ -17,9 +17,10 @@ const baseTsOptions: ts.CompilerOptions = {
 
 export interface JsDocTagOptions {
   /**
-   * An array of names of jsdoc tags that must exist.
+   * An array of names of jsdoc tags, one of which must exist. If no tags are provided, there are no
+   * required tags.
    */
-  required?: string[];
+  requireAtLeastOne?: string[];
 
   /**
    * An array of names of jsdoc tags that must not exist.
@@ -316,15 +317,16 @@ class ResolvedDeclarationEmitter {
 
   private processJsDocTags(node: ts.Node, tagOptions: JsDocTagOptions) {
     const jsDocTags = getJsDocTags(node);
-    const missingRequiredTags =
-        tagOptions.required.filter(requiredTag => jsDocTags.every(tag => tag !== requiredTag));
-    if (missingRequiredTags.length) {
+    const requireAtLeastOne = tagOptions.requireAtLeastOne;
+    const isMissingAnyRequiredTag = requireAtLeastOne != null && requireAtLeastOne.length > 0 &&
+        jsDocTags.every(tag => requireAtLeastOne.indexOf(tag) === -1);
+    if (isMissingAnyRequiredTag) {
       this.diagnostics.push({
         type: 'error',
         message: createErrorMessage(
-            node, 'Required jsdoc tags - ' +
-                missingRequiredTags.map(tag => `"@${tag}"`).join(', ') +
-                ` - are missing on ${getName(node)}.`)
+            node, 'Required jsdoc tags - One of the tags: ' +
+                requireAtLeastOne.map(tag => `"@${tag}"`).join(', ') +
+                ` - must exist on ${getName(node)}.`)
       });
     }
     const bannedTagsFound =
@@ -436,7 +438,7 @@ function hasModifier(node: ts.Node, modifierKind: ts.SyntaxKind): boolean {
 }
 
 function applyDefaultTagOptions(tagOptions: JsDocTagOptions | undefined): JsDocTagOptions {
-  return {required: [], banned: [], toCopy: [], ...tagOptions};
+  return {requireAtLeastOne: [], banned: [], toCopy: [], ...tagOptions};
 }
 
 function getName(node: any) {
diff --git a/tools/ts-api-guardian/test/unit_test.ts b/tools/ts-api-guardian/test/unit_test.ts
index e9de608a67..625cf5d2d4 100644
--- a/tools/ts-api-guardian/test/unit_test.ts
+++ b/tools/ts-api-guardian/test/unit_test.ts
@@ -531,8 +531,8 @@ describe('unit test', () => {
     `;
     checkThrows(
         {'file.d.ts': input},
-        'file.d.ts(2,1): error: Required jsdoc tags - "@stable" - are missing on `A`.',
-        {exportTags: {required: ['stable']}});
+        'file.d.ts(2,1): error: Required jsdoc tags - One of the tags: "@stable" - must exist on `A`.',
+        {exportTags: {requireAtLeastOne: ['stable']}});
   });
 
   it('should throw on missing required jsdoc tags on fields', () => {
@@ -544,8 +544,8 @@ describe('unit test', () => {
     `;
     checkThrows(
         {'file.d.ts': input},
-        'file.d.ts(3,3): error: Required jsdoc tags - "@stable" - are missing on `value`.',
-        {memberTags: {required: ['stable']}});
+        'file.d.ts(3,3): error: Required jsdoc tags - One of the tags: "@stable" - must exist on `value`.',
+        {memberTags: {requireAtLeastOne: ['stable']}});
   });
 
   it('should throw on missing required jsdoc tags on parameters', () => {
@@ -557,8 +557,21 @@ describe('unit test', () => {
     `;
     checkThrows(
         {'file.d.ts': input},
-        'file.d.ts(3,7): error: Required jsdoc tags - "@stable" - are missing on `param`.',
-        {paramTags: {required: ['stable']}});
+        'file.d.ts(3,7): error: Required jsdoc tags - One of the tags: "@stable" - must exist on `param`.',
+        {paramTags: {requireAtLeastOne: ['stable']}});
+  });
+
+  it('should require at least one of the requireOnOf tags', () => {
+    const input = `
+      /** @experimental */
+      export declare class A {
+        foo(param: number): void;
+      }
+    `;
+    checkThrows(
+        {'file.d.ts': input},
+        'file.d.ts(3,7): error: Required jsdoc tags - One of the tags: "@stable", "@foo", "@bar" - must exist on `param`.',
+        {paramTags: {requireAtLeastOne: ['stable', 'foo', 'bar']}});
   });
 });