docs: clean up router api doc (#31476)

PR Close #31476

packages/router/upgrade/src/upgrade.ts

@@ -12,12 +12,12 @@ import {Router} from '@angular/router';
 import {UpgradeModule} from '@angular/upgrade/static';
 
 /**
- * @description
+ * Creates an initializer that sets up `ngRoute` integration
+ * along with setting up the Angular router.
  *
- * Creates an initializer that in addition to setting up the Angular
- * router sets up the ngRoute integration.
+ * @usageNotes
  *
- * ```
+ * <code-example language="typescript" linenums="false">
  * @NgModule({
  *  imports: [
  *   RouterModule.forRoot(SOME_ROUTES),
@@ -30,7 +30,7 @@ import {UpgradeModule} from '@angular/upgrade/static';
  * export class AppModule {
  *   ngDoBootstrap() {}
  * }
- * ```
+ * </code-example>
  *
  * @publicApi
  */
@@ -49,12 +49,14 @@ export function locationSyncBootstrapListener(ngUpgrade: UpgradeModule) {
 }
 
 /**
- * @description
+ * Sets up a location change listener to trigger `history.pushState`.
+ * Works around the problem that `onPopState` does not trigger `history.pushState`.
+ * Must be called *after* calling `UpgradeModule.bootstrap`.
  *
- * Sets up a location synchronization.
- *
- * History.pushState does not fire onPopState, so the Angular location
- * doesn't detect it. The workaround is to attach a location change listener
+ * @param ngUpgrade The upgrade NgModule.
+ * @param urlType The location strategy.
+ * @see `HashLocationStrategy`
+ * @see `PathLocationStrategy`
  *
  * @publicApi
  */
@@ -87,7 +89,7 @@ export function setUpLocationSync(ngUpgrade: UpgradeModule, urlType: 'path' | 'h
 }
 
 /**
- * Normalize and parse a URL.
+ * Normalizes and parses a URL.
  *
  * - Normalizing means that a relative URL will be resolved into an absolute URL in the context of
  *   the application document.