Visitar URL original
docs: fix @param names that don't match their parameters · angular/angular@dcb29a9 · GitHub
Skip to content

Commit dcb29a9

Browse files
MeAkibcrisbeto
MeAkib
authored and
crisbeto
committed
docs: fix @PARAM names that don't match their parameters
The API reference only attaches a `@param` description to a parameter when the names match. Several APIs documented parameters under a different name than the one in the signature, so angular.dev rendered those parameters with an empty description. Update the JSDoc to use the actual parameter names: - core: `ViewContainerRef.move()` documented `index` instead of `currentIndex`. - core: `inject()` still documented the `flags` parameter, which was replaced by `options` when `InjectFlags` was removed from the public API. Use the same description as the other `inject()` overloads. - core: `twoWayBinding()` documented `eventName` instead of `publicName`. - common: `Location.subscribe()` documented `value` and `exception` instead of the `onNext` and `onThrow` callbacks, and didn't document `onReturn`. - common/upgrade: `UrlCodec.encodeSearch()`, `decodeSearch()`, `encodeHash()` and `decodeHash()` documented `path` instead of `search` or `hash`, and the first `normalize()` overload documented `path` instead of `href`. Also fix a "has string" typo. - router: `DefaultTitleStrategy.updateTitle()` documented a `title` parameter instead of `snapshot`. Also update its description, since it builds the title from the router state rather than setting a given value. - forms: `minDate()` and `maxDate()` documented `minDate` and `maxDate` instead of `minDateValue` and `maxDateValue`. Verified by rebuilding the docs with `//adev:build` and checking that each of these parameters now has a description in the generated API reference pages, and that no other `@param` name mismatches remain besides `IterableChanges.forEachOperation` (which documents its callback's arguments) and the `QueryList` constructor. (cherry picked from commit 6e02460)
1 parent 276248f commit dcb29a9

8 files changed

Lines changed: 18 additions & 17 deletions

File tree

‎packages/common/src/location/location.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -258,8 +258,9 @@ export class Location implements OnDestroy {
258258
* Note: `Location.go()` does not trigger the `popState` event in the browser. Use
259259
* `Location.onUrlChange()` to subscribe to URL changes instead.
260260
*
261-
* @param value Event that is triggered when the state history changes.
262-
* @param exception The exception to throw.
261+
* @param onNext Callback invoked with the event that is triggered when the state history changes.
262+
* @param onThrow Callback invoked with the exception if an error occurs.
263+
* @param onReturn Callback invoked when the subscription completes.
263264
*
264265
* @see [onpopstate](https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onpopstate)
265266
*

‎packages/common/upgrade/src/params.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,35 +29,35 @@ export abstract class UrlCodec {
2929
/**
3030
* Encodes the search string from the provided string or object
3131
*
32-
* @param path The path string or object
32+
* @param search The search string or object
3333
*/
3434
abstract encodeSearch(search: string | {[k: string]: unknown}): string;
3535

3636
/**
3737
* Decodes the search objects from the provided string
3838
*
39-
* @param path The path string
39+
* @param search The search string
4040
*/
4141
abstract decodeSearch(search: string): {[k: string]: unknown};
4242

4343
/**
4444
* Encodes the hash from the provided string
4545
*
46-
* @param path The hash string
46+
* @param hash The hash string
4747
*/
4848
abstract encodeHash(hash: string): string;
4949

5050
/**
5151
* Decodes the hash from the provided string
5252
*
53-
* @param path The hash string
53+
* @param hash The hash string
5454
*/
5555
abstract decodeHash(hash: string): string;
5656

5757
/**
5858
* Normalizes the URL from the provided string
5959
*
60-
* @param path The URL string
60+
* @param href The URL string
6161
*/
6262
abstract normalize(href: string): string;
6363

@@ -66,7 +66,7 @@ export abstract class UrlCodec {
6666
*
6767
* @param path The URL path
6868
* @param search The search object
69-
* @param hash The has string
69+
* @param hash The hash string
7070
* @param baseUrl The base URL for the URL
7171
*/
7272
abstract normalize(

‎packages/core/src/di/injector_compatibility.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -235,9 +235,9 @@ export function inject(token: HostAttributeToken, options: {optional: false}): s
235235
* - In a stackframe of a function call in a DI context
236236
*
237237
* @param token A token that represents a dependency that should be injected.
238-
* @param flags Optional flags that control how injection is executed.
239-
* The flags correspond to injection strategies that can be specified with
240-
* parameter decorators `@Host`, `@Self`, `@SkipSelf`, and `@Optional`.
238+
* @param options Control how injection is executed. Options correspond to injection strategies
239+
* that can be specified with parameter decorators `@Host`, `@Self`, `@SkipSelf`, and
240+
* `@Optional`.
241241
* @returns the injected value if operation is successful, `null` otherwise.
242242
* @throws if called outside of a supported context.
243243
*

‎packages/core/src/linker/view_container_ref.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -266,7 +266,7 @@ export abstract class ViewContainerRef {
266266
/**
267267
* Moves a view to a new location in this container.
268268
* @param viewRef The view to move.
269-
* @param index The 0-based index of the new location.
269+
* @param currentIndex The 0-based index of the new location.
270270
* @returns The moved `ViewRef` instance.
271271
*/
272272
abstract move(viewRef: ViewRef, currentIndex: number): ViewRef;

‎packages/core/src/render3/dynamic_bindings.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -197,7 +197,7 @@ export function outputBinding<T>(eventName: string, listener: (event: T) => unkn
197197

198198
/**
199199
* Creates a two-way binding.
200-
* @param eventName Public name of the two-way compatible input.
200+
* @param publicName Public name of the two-way compatible input.
201201
* @param value Writable signal from which to get the current value and to which to write new
202202
* values.
203203
*

‎packages/forms/signals/src/api/rules/validation/max_date.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ import {maxDateError} from './validation_errors';
2424
* or `new Date()`, is offset by the user's time zone, which can make the limit date itself invalid.
2525
*
2626
* @param path Path of the field to validate
27-
* @param maxDate The maximum date, or a LogicFn that returns the maximum date.
27+
* @param maxDateValue The maximum date, or a LogicFn that returns the maximum date.
2828
* @param config Optional, allows providing any of the following options:
2929
* - `error`: Custom validation error(s) to be used instead of the default `maxDateError()`
3030
* or a function that receives the `FieldContext` and returns custom validation error(s).

‎packages/forms/signals/src/api/rules/validation/min_date.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ import {minDateError} from './validation_errors';
2424
* or `new Date()`, is offset by the user's time zone, which can make the limit date itself invalid.
2525
*
2626
* @param path Path of the field to validate
27-
* @param minDate The minimum date, or a LogicFn that returns the minimum date.
27+
* @param minDateValue The minimum date, or a LogicFn that returns the minimum date.
2828
* @param config Optional, allows providing any of the following options:
2929
* - `error`: Custom validation error(s) to be used instead of the default `minDateError()`
3030
* or a function that receives the `FieldContext` and returns custom validation error(s).

‎packages/router/src/page_title_strategy.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,9 @@ export class DefaultTitleStrategy extends TitleStrategy {
7272
}
7373

7474
/**
75-
* Sets the title of the browser to the given value.
75+
* Sets the title of the browser to the title built from the given router state.
7676
*
77-
* @param title The `pageTitle` from the deepest primary route.
77+
* @param snapshot The current router state. The title is taken from the deepest primary route.
7878
*/
7979
override updateTitle(snapshot: RouterStateSnapshot): void {
8080
const title = this.buildTitle(snapshot);

0 commit comments

Comments
 (0)