Add additional comments to new router (#38986)

Expanded app-render.


## Bug

- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have helpful link attached, see `contributing.md`

## Feature

- [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have helpful link attached, see `contributing.md`

## Documentation / Examples

- [ ] Make sure the linting passes by running `pnpm lint`
- [ ] The examples guidelines are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing.md#adding-examples)

packages/next/client/components/app-router.client.tsx

@@ -41,6 +41,7 @@ function fetchFlight(
     JSON.stringify(flightRouterState)
   )
 
+  // TODO-APP: Verify that TransformStream is supported.
   const { readable, writable } = new TransformStream()
 
   fetch(flightUrl.toString()).then((res) => {

packages/next/client/components/hooks-client.ts

@@ -12,16 +12,25 @@ import {
   AppTreeContext,
 } from '../../shared/lib/app-router-context'
 
+/**
+ * Get the current search params. For example useSearchParams() would return {"foo": "bar"} when ?foo=bar
+ */
 export function useSearchParams() {
   return useContext(SearchParamsContext)
 }
 
+/**
+ * Get an individual search param. For example useSearchParam("foo") would return "bar" when ?foo=bar
+ */
 export function useSearchParam(key: string): string | string[] {
   const params = useContext(SearchParamsContext)
   return params[key]
 }
 
 // TODO-APP: Move the other router context over to this one
+/**
+ * Get the router methods. For example router.push('/dashboard')
+ */
 export function useRouter(): import('../../shared/lib/app-router-context').AppRouterInstance {
   return useContext(AppRouterContext)
 }
@@ -31,6 +40,9 @@ export function useRouter(): import('../../shared/lib/app-router-context').AppRo
 //   return useContext(ParamsContext)
 // }
 
+/**
+ * Get the current pathname. For example usePathname() on /dashboard?foo=bar would return "/dashboard"
+ */
 export function usePathname(): string {
   return useContext(PathnameContext)
 }
@@ -40,6 +52,10 @@ export function usePathname(): string {
 //   return useContext(LayoutSegmentsContext)
 // }
 
+// TODO-APP: Expand description when the docs are written for it.
+/**
+ * Get the current segment one level down from the layout.
+ */
 export function useSelectedLayoutSegment(
   parallelRouteKey: string = 'children'
 ): string {