docs: update api reference doc for router-link-active directive (#38247)

Edits and organizes the usage information for the directive.

PR Close #38247

packages/router/src/directives/router_link_active.ts

@@ -19,44 +19,49 @@ import {RouterLink, RouterLinkWithHref} from './router_link';
  *
  * @description
  *
- * Lets you add a CSS class to an element when the link's route becomes active.
+ * Tracks whether the linked route of an element is currently active, and allows you
+ * to specify one or more CSS classes to add to the element when the linked route
+ * is active.
  *
- * This directive lets you add a CSS class to an element when the link's route
+ * Use this directive to create a visual distinction for elements associated with an active route.
- * becomes active.
+ * For example, the following code highlights the word "Bob" when the the router
- *
+ * activates the associated route:
- * Consider the following example:
  *
  * ```
  * <a routerLink="/user/bob" routerLinkActive="active-link">Bob</a>
  * ```
  *
- * When the url is either '/user' or '/user/bob', the active-link class will
+ * Whenever the URL is either '/user' or '/user/bob', the "active-link" class is
- * be added to the `a` tag. If the url changes, the class will be removed.
+ * added to the anchor tag. If the URL changes, the class is removed.
  *
- * You can set more than one class, as follows:
+ * You can set more than one class using a space-separated string or an array.
+ * For example:
  *
  * ```
  * <a routerLink="/user/bob" routerLinkActive="class1 class2">Bob</a>
  * <a routerLink="/user/bob" [routerLinkActive]="['class1', 'class2']">Bob</a>
  * ```
  *
- * You can configure RouterLinkActive by passing `exact: true`. This will add the classes
+ * To add the classes only when the URL matches the link exactly, add the option `exact: true`:
- * only when the url matches the link exactly.
  *
  * ```
  * <a routerLink="/user/bob" routerLinkActive="active-link" [routerLinkActiveOptions]="{exact:
  * true}">Bob</a>
  * ```
  *
- * You can assign the RouterLinkActive instance to a template variable and directly check
+ * To directly check the `isActive` status of the link, assign the `RouterLinkActive`
- * the `isActive` status.
+ * instance to a template variable.
+ * For example, the following checks the status without assigning any CSS classes:
+ *
  * ```
  * <a routerLink="/user/bob" routerLinkActive #rla="routerLinkActive">
  *   Bob {{ rla.isActive ? '(already open)' : ''}}
  * </a>
  * ```
  *
- * Finally, you can apply the RouterLinkActive directive to an ancestor of a RouterLink.
+ * You can apply the `RouterLinkActive` directive to an ancestor of linked elements.
+ * For example, the following sets the active-link class on the `<div>`  parent tag
+ * when the URL is either '/user/jim' or '/user/bob'.
  *
  * ```
  * <div routerLinkActive="active-link" [routerLinkActiveOptions]="{exact: true}">
@@ -65,9 +70,6 @@ import {RouterLink, RouterLinkWithHref} from './router_link';
  * </div>
  * ```
  *
- * This will set the active-link class on the div tag if the url is either '/user/jim' or
- * '/user/bob'.
- *
  * @ngModule RouterModule
  *
  * @publicApi