diff --git a/packages/core/src/application_ref.ts b/packages/core/src/application_ref.ts
index 4ca238321c..a701f7518e 100644
--- a/packages/core/src/application_ref.ts
+++ b/packages/core/src/application_ref.ts
@@ -135,7 +135,7 @@ export class NgProbeToken {
/**
* Creates a platform.
- * Platforms have to be eagerly created via this function.
+ * Platforms must be created on launch using this function.
*
* @publicApi
*/
@@ -153,7 +153,13 @@ export function createPlatform(injector: Injector): PlatformRef {
}
/**
- * Creates a factory for a platform
+ * Creates a factory for a platform. Can be used to provide or override `Providers` specific to
+ * your applciation's runtime needs, such as `PLATFORM_INITIALIZER` and `PLATFORM_ID`.
+ * @param parentPlatformFactory Another platform factory to modify. Allows you to compose factories
+ * to build up configurations that might be required by different libraries or parts of the
+ * application.
+ * @param name Identifies the new platform factory.
+ * @param providers A set of dependency providers for platforms created with the new factory.
*
* @publicApi
*/
@@ -182,7 +188,7 @@ export function createPlatformFactory(
}
/**
- * Checks that there currently is a platform which contains the given token as a provider.
+ * Checks that there is currently a platform that contains the given token as a provider.
*
* @publicApi
*/
@@ -202,7 +208,8 @@ export function assertPlatform(requiredToken: any): PlatformRef {
}
/**
- * Destroy the existing platform.
+ * Destroys the current Angular platform and all Angular applications on the page.
+ * Destroys all modules and listeners registered with the platform.
*
* @publicApi
*/
@@ -259,12 +266,11 @@ export interface BootstrapOptions {
}
/**
- * The Angular platform is the entry point for Angular on a web page. Each page
- * has exactly one platform, and services (such as reflection) which are common
+ * The Angular platform is the entry point for Angular on a web page.
+ * Each page has exactly one platform. Services (such as reflection) which are common
* to every Angular application running on the page are bound in its scope.
- *
- * A page's platform is initialized implicitly when a platform is created via a platform factory
- * (e.g. {@link platformBrowser}), or explicitly by calling the {@link createPlatform} function.
+ * A page's platform is initialized implicitly when a platform is created using a platform
+ * factory such as `PlatformBrowser`, or explicitly by calling the `createPlatform()` function.
*
* @publicApi
*/
@@ -278,11 +284,11 @@ export class PlatformRef {
constructor(private _injector: Injector) {}
/**
- * Creates an instance of an `@NgModule` for the given platform
- * for offline compilation.
+ * Creates an instance of an `@NgModule` for the given platform for offline compilation.
*
* @usageNotes
- * ### Simple Example
+ *
+ * The following example creates the NgModule for a browser platform.
*
* ```typescript
* my_module.ts:
@@ -384,14 +390,14 @@ export class PlatformRef {
}
/**
- * Register a listener to be called when the platform is disposed.
+ * Registers a listener to be called when the platform is destroyed.
*/
onDestroy(callback: () => void): void {
this._destroyListeners.push(callback);
}
/**
- * Retrieve the platform {@link Injector}, which is the parent injector for
+ * Retrieves the platform {@link Injector}, which is the parent injector for
* every Angular application on the page and provides singleton providers.
*/
get injector(): Injector {
@@ -399,7 +405,8 @@ export class PlatformRef {
}
/**
- * Destroy the Angular platform and all Angular applications on the page.
+ * Destroys the current Angular platform and all Angular applications on the page.
+ * Destroys all modules and listeners registered with the platform.
*/
destroy() {
if (this._destroyed) {
diff --git a/packages/platform-browser/src/browser.ts b/packages/platform-browser/src/browser.ts
index 9fdae91883..65be438171 100644
--- a/packages/platform-browser/src/browser.ts
+++ b/packages/platform-browser/src/browser.ts
@@ -58,6 +58,9 @@ export const BROWSER_SANITIZATION_PROVIDERS__POST_R3__ = [];
export const BROWSER_SANITIZATION_PROVIDERS = BROWSER_SANITIZATION_PROVIDERS__PRE_R3__;
/**
+ * A factory function that returns a `PlatformRef` instance associated with browser service
+ * providers.
+ *
* @publicApi
*/
export const platformBrowser: (extraProviders?: StaticProvider[]) => PlatformRef =
diff --git a/packages/platform-browser/src/browser/meta.ts b/packages/platform-browser/src/browser/meta.ts
index 7b33e66cb0..aa5a421b54 100644
--- a/packages/platform-browser/src/browser/meta.ts
+++ b/packages/platform-browser/src/browser/meta.ts
@@ -10,7 +10,11 @@ import {DOCUMENT, ɵDomAdapter as DomAdapter, ɵgetDOM as getDOM} from '@angular
import {Inject, Injectable, ɵɵinject} from '@angular/core';
/**
- * Represents a meta element.
+ * Represents the attributes of an HTML `` element. The element itself is
+ * represented by the internal `HTMLMetaElement`.
+ *
+ * @see [HTML meta tag](https://developer.mozilla.org/docs/Web/HTML/Element/meta)
+ * @see `Meta`
*
* @publicApi
*/
@@ -30,14 +34,31 @@ export type MetaDefinition = {
};
/**
- * Factory to create Meta service.
+ * Factory to create a `Meta` service instance for the current DOM document.
*/
export function createMeta() {
return new Meta(ɵɵinject(DOCUMENT));
}
/**
- * A service that can be used to get and add meta tags.
+ * A service for managing HTML `` tags.
+ *
+ * Properties of the `MetaDefinition` object match the attributes of the
+ * HTML `` tag. These tags define document metadata that is important for
+ * things like configuring a Content Security Policy, defining browser compatibility
+ * and security settings, setting HTTP Headers, defining rich content for social sharing,
+ * and Search Engine Optimization (SEO).
+ *
+ * To identify specific `` tags in a document, use an attribute selection
+ * string in the format `"tag_attribute='value string'"`.
+ * For example, an `attrSelector` value of `"name='description'"` matches a tag
+ * whose `name` attribute has the value `"description"`.
+ * Selectors are used with the `querySelector()` Document method,
+ * in the format `meta[{attrSelector}]`.
+ *
+ * @see [HTML meta tag](https://developer.mozilla.org/docs/Web/HTML/Element/meta)
+ * @see [Document.querySelector()](https://developer.mozilla.org/docs/Web/API/Document/querySelector)
+ *
*
* @publicApi
*/
@@ -47,12 +68,29 @@ export class Meta {
constructor(@Inject(DOCUMENT) private _doc: any) {
this._dom = getDOM();
}
-
+ /**
+ * Retrieves or creates a specific `` tag element in the current HTML document.
+ * In searching for an existing tag, Angular attempts to match the `name` or `property` attribute
+ * values in the provided tag definition, and verifies that all other attribute values are equal.
+ * If an existing element is found, it is returned and is not modified in any way.
+ * @param tag The definition of a `` element to match or create.
+ * @param forceCreation True to create a new element without checking whether one already exists.
+ * @returns The existing element with the same attributes and values if found,
+ * the new element if no match is found, or `null` if the tag parameter is not defined.
+ */
addTag(tag: MetaDefinition, forceCreation: boolean = false): HTMLMetaElement|null {
if (!tag) return null;
return this._getOrCreateElement(tag, forceCreation);
}
+ /**
+ * Retrieves or creates a set of `` tag elements in the current HTML document.
+ * In searching for an existing tag, Angular attempts to match the `name` or `property` attribute
+ * values in the provided tag definition, and verifies that all other attribute values are equal.
+ * @param tags An array of tag definitions to match or create.
+ * @param forceCreation True to create new elements without checking whether they already exist.
+ * @returns The matching elements if found, or the new elements.
+ */
addTags(tags: MetaDefinition[], forceCreation: boolean = false): HTMLMetaElement[] {
if (!tags) return [];
return tags.reduce((result: HTMLMetaElement[], tag: MetaDefinition) => {
@@ -63,17 +101,38 @@ export class Meta {
}, []);
}
+ /**
+ * Retrieves a `` tag element in the current HTML document.
+ * @param attrSelector The tag attribute and value to match against, in the format
+ * `"tag_attribute='value string'"`.
+ * @returns The matching element, if any.
+ */
getTag(attrSelector: string): HTMLMetaElement|null {
if (!attrSelector) return null;
return this._doc.querySelector(`meta[${attrSelector}]`) || null;
}
+ /**
+ * Retrieves a set of `` tag elements in the current HTML document.
+ * @param attrSelector The tag attribute and value to match against, in the format
+ * `"tag_attribute='value string'"`.
+ * @returns The matching elements, if any.
+ */
getTags(attrSelector: string): HTMLMetaElement[] {
if (!attrSelector) return [];
const list /*NodeList*/ = this._doc.querySelectorAll(`meta[${attrSelector}]`);
return list ? [].slice.call(list) : [];
}
+ /**
+ * Modifies an existing `` tag element in the current HTML document.
+ * @param tag The tag description with which to replace the existing tag content.
+ * @param selector A tag attribute and value to match against, to identify
+ * an existing tag. A string in the format `"tag_attribute=`value string`"`.
+ * If not supplied, matches a tag with the same `name` or `property` attribute value as the
+ * replacement tag.
+ * @return The modified element.
+ */
updateTag(tag: MetaDefinition, selector?: string): HTMLMetaElement|null {
if (!tag) return null;
selector = selector || this._parseSelector(tag);
@@ -84,10 +143,19 @@ export class Meta {
return this._getOrCreateElement(tag, true);
}
+ /**
+ * Removes an existing `` tag element from the current HTML document.
+ * @param attrSelector A tag attribute and value to match against, to identify
+ * an existing tag. A string in the format `"tag_attribute=`value string`"`.
+ */
removeTag(attrSelector: string): void {
this.removeTagElement(this.getTag(attrSelector)!);
}
+ /**
+ * Removes an existing `` tag element from the current HTML document.
+ * @param meta The tag definition to match against to identify an existing tag.
+ */
removeTagElement(meta: HTMLMetaElement): void {
if (meta) {
this._dom.remove(meta);