fix(@angular-devkit/build-angular): mark programmatic builder execution functions as experimental

While the builders when executed via the Angular CLI and their associated options are considered stable, the programmatic APIs are not considered officially supported and are not subject to the breaking change guarantees of SemVer.
The programmatic APIs for the builders are now explicitly marked as experimental. This allows the package to use a stable versioning scheme while also continuing to provide access to the experimental programmatic API elements of the package.

Author: clydin

packages/angular_devkit/build_angular/src/browser/index.ts

@@ -79,6 +79,9 @@ import { Schema as BrowserBuilderSchema } from './schema';
 
 const cacheDownlevelPath = cachingDisabled ? undefined : findCachePath('angular-build-dl');
 
+/**
+ * @experimental Direct usage of this type is considered experimental.
+ */
 export type BrowserBuilderOutput = json.JsonObject &
   BuilderOutput & {
     baseOutputPath: string;
@@ -186,6 +189,9 @@ async function initialize(
   return { config: transformedConfig || config, projectRoot, projectSourceRoot, i18n };
 }
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 // tslint:disable-next-line: no-big-function
 export function buildWebpackBrowser(
   options: BrowserBuilderSchema,

packages/angular_devkit/build_angular/src/dev-server/index.ts

@@ -62,16 +62,21 @@ const devServerBuildOverriddenKeys: (keyof DevServerBuilderOptions)[] = [
   'deployUrl',
 ];
 
+/**
+ * @experimental Direct usage of this type is considered experimental.
+ */
 export type DevServerBuilderOutput = DevServerBuildOutput & {
   baseUrl: string;
 };
 
 /**
- * Reusable implementation of the build angular webpack dev server builder.
+ * Reusable implementation of the Angular Webpack development server builder.
  * @param options Dev Server options.
  * @param context The build context.
  * @param transforms A map of transforms that can be used to hook into some logic (such as
  *     transforming webpack configuration before passing it to webpack).
+ *
+ * @experimental Direct usage of this function is considered experimental.
  */
 // tslint:disable-next-line: no-big-function
 export function serveWebpackBrowser(

packages/angular_devkit/build_angular/src/extract-i18n/index.ts

@@ -121,6 +121,9 @@ class NoEmitPlugin {
   }
 }
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 export async function execute(
   options: ExtractI18nBuilderOptions,
   context: BuilderContext,

packages/angular_devkit/build_angular/src/karma/index.ts

@@ -60,6 +60,9 @@ async function initialize(
   ];
 }
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 export function execute(
   options: KarmaBuilderOptions,
   context: BuilderContext,

packages/angular_devkit/build_angular/src/ng-packagr/index.ts

@@ -26,6 +26,9 @@ async function initialize(
   return packager;
 }
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 export function execute(
   options: NgPackagrBuilderOptions,
   context: BuilderContext,

packages/angular_devkit/build_angular/src/protractor/index.ts

@@ -85,6 +85,9 @@ async function updateWebdriver() {
 
 export { ProtractorBuilderOptions };
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 export async function execute(
   options: ProtractorBuilderOptions,
   context: BuilderContext,

packages/angular_devkit/build_angular/src/server/index.ts

@@ -31,7 +31,9 @@ import {
 import { JsonCompilationStats, webpackStatsLogger } from '../webpack/utils/stats';
 import { Schema as ServerBuilderOptions } from './schema';
 
-// If success is true, outputPath should be set.
+/**
+ * @experimental Direct usage of this type is considered experimental.
+ */
 export type ServerBuilderOutput = json.JsonObject & BuilderOutput & {
   baseOutputPath: string;
   outputPaths: string[];
@@ -43,6 +45,9 @@ export type ServerBuilderOutput = json.JsonObject & BuilderOutput & {
 
 export { ServerBuilderOptions };
 
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
 export function execute(
   options: ServerBuilderOptions,
   context: BuilderContext,