docs: update api ref doc for platform browser (#37186)

Edit descriptions, usage examples, and add links to be complete and consistent with API reference doc style

PR Close #37186

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
+ * The Angular platform is the entry point for Angular on a web page.
- * has exactly one platform, and services (such as reflection) which are common
+ * 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 using a platform
- * A page's platform is initialized implicitly when a platform is created via a platform factory
+ * factory such as `PlatformBrowser`, or explicitly by calling the `createPlatform()` function.
- * (e.g. {@link platformBrowser}), or explicitly by calling the {@link createPlatform} function.
  *
  * @publicApi
  */
@@ -278,11 +284,11 @@ export class PlatformRef {
   constructor(private _injector: Injector) {}
 
   /**
-   * Creates an instance of an `@NgModule` for the given platform
+   * Creates an instance of an `@NgModule` for the given platform for offline compilation.
-   * 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) {

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 =

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 `<meta>` 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 `<meta>` tags.
+ *
+ * Properties of the `MetaDefinition` object match the attributes of the
+ * HTML `<meta>` 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 `<meta>` 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 `<meta>` 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 `<meta>` 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 `<meta>` 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 `<meta>` 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 `<meta>` 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 `<meta>` 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 `<meta>` 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 `<meta>` 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);