docs(methods): update component method documentation #4145

core/src/components/action-sheet/action-sheet.tsx

@@ -210,16 +210,15 @@ export class ActionSheet implements ComponentInterface, OverlayInterface {
 
   /**
    * Dismiss the action sheet overlay after it has been presented.
+   * This is a no-op if the overlay has not been presented yet. If you want
+   * to remove an overlay from the DOM that was never presented, use the
+   * [remove](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) method.
    *
    * @param data Any data to emit in the dismiss events.
    * @param role The role of the element that is dismissing the action sheet.
    * This can be useful in a button handler for determining which button was
-   * clicked to dismiss the action sheet.
-   * Some examples include: ``"cancel"`, `"destructive"`, "selected"`, and `"backdrop"`.
-   *
-   * This is a no-op if the overlay has not been presented yet. If you want
-   * to remove an overlay from the DOM that was never presented, use the
-   * [remove](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) method.
+   * clicked to dismiss the action sheet. Some examples include:
+   * `"cancel"`, `"destructive"`, `"selected"`, and `"backdrop"`.
    */
   @Method()
   async dismiss(data?: any, role?: string): Promise<boolean> {

core/src/components/alert/alert.tsx

@@ -432,16 +432,15 @@ export class Alert implements ComponentInterface, OverlayInterface {
 
   /**
    * Dismiss the alert overlay after it has been presented.
+   * This is a no-op if the overlay has not been presented yet. If you want
+   * to remove an overlay from the DOM that was never presented, use the
+   * [remove](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) method.
    *
    * @param data Any data to emit in the dismiss events.
    * @param role The role of the element that is dismissing the alert.
    * This can be useful in a button handler for determining which button was
-   * clicked to dismiss the alert.
-   * Some examples include: ``"cancel"`, `"destructive"`, "selected"`, and `"backdrop"`.
-   *
-   * This is a no-op if the overlay has not been presented yet. If you want
-   * to remove an overlay from the DOM that was never presented, use the
-   * [remove](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) method.
+   * clicked to dismiss the alert. Some examples include:
+   * `"cancel"`, `"destructive"`, `"selected"`, and `"backdrop"`.
    */
   @Method()
   async dismiss(data?: any, role?: string): Promise<boolean> {

core/src/components/app/app.tsx

@@ -68,6 +68,8 @@ export class App implements ComponentInterface {
    * a result of another user action. (Ex: We focus the first element
    * inside of a popover when the user presents it, but the popover is not always
    * presented as a result of keyboard action.)
+   *
+   * @param elements An array of HTML elements to set focus on.
    */
   @Method()
   async setFocus(elements: HTMLElement[]) {

core/src/components/datetime/datetime.tsx

@@ -524,6 +524,8 @@ export class Datetime implements ComponentInterface {
    * Confirms the selected datetime value, updates the
    * `value` property, and optionally closes the popover
    * or modal that the datetime was presented in.
+   *
+   * @param closeOverlay If `true`, closes the parent overlay. Defaults to `false`.
    */
   @Method()
   async confirm(closeOverlay = false) {
@@ -559,6 +561,8 @@ export class Datetime implements ComponentInterface {
    * Resets the internal state of the datetime but does not update the value.
    * Passing a valid ISO-8601 string will reset the state of the component to the provided date.
    * If no value is provided, the internal state will be reset to the clamped value of the min, max and today.
+   *
+   * @param startDate a valid [ISO-8601 string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format) to reset the datetime state to.
    */
   @Method()
   async reset(startDate?: string) {
@@ -570,6 +574,8 @@ export class Datetime implements ComponentInterface {
    * optionally closes the popover
    * or modal that the datetime was
    * presented in.
+   *
+   * @param closeOverlay If `true`, closes the parent overlay. Defaults to `false`.
    */
   @Method()
   async cancel(closeOverlay = false) {

core/src/components/loading/loading.tsx

@@ -264,16 +264,15 @@ export class Loading implements ComponentInterface, OverlayInterface {
 
   /**
    * Dismiss the loading overlay after it has been presented.
+   * This is a no-op if the overlay has not been presented yet. If you want
+   * to remove an overlay from the DOM that was never presented, use the
+   * [remove](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) method.
    *
    * @param data Any data to emit in the dismiss events.
    * @param role The role of the element that is dismissing the loading.
    * This can be useful in a button handler for determining which button was
-   * clicked to dismiss the loading.
-   * Some examples include: ``"cancel"`, `"destructive"`, "selected"`, and `"backdrop"`.
-   *
-   * This is a no-op if the overlay has not been presented yet. If you want
-   * to remove an overlay from the DOM that was never presented, use the
-   * [remove](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) method.
+   * clicked to dismiss the loading. Some examples include:
+   * `"cancel"`, `"destructive"`, `"selected"`, and `"backdrop"`.
    */
   @Method()
   async dismiss(data?: any, role?: string): Promise<boolean> {

core/src/components/menu/menu.tsx

@@ -353,7 +353,7 @@ export class Menu implements ComponentInterface, MenuI {
   }
 
   /**
-   * Returns `true` is the menu is active.
+   * Returns `true` if the menu is active.
    *
    * A menu is active when it can be opened or closed, meaning it's enabled
    * and it's not part of a `ion-split-pane`.
@@ -366,6 +366,10 @@ export class Menu implements ComponentInterface, MenuI {
   /**
    * Opens the menu. If the menu is already open or it can't be opened,
    * it returns `false`.
+   *
+   * @param animated If `true`, the menu will animate when opening.
+   * If `false`, the menu will open instantly without animation.
+   * Defaults to `true`.
    */
   @Method()
   open(animated = true): Promise<boolean> {
@@ -375,24 +379,42 @@ export class Menu implements ComponentInterface, MenuI {
   /**
    * Closes the menu. If the menu is already closed or it can't be closed,
    * it returns `false`.
+   *
+   * @param animated If `true`, the menu will animate when closing. If `false`,
+   * the menu will close instantly without animation. Defaults to `true`.
+   * @param role The role of the element that is closing the menu.
+   * This can be useful in a button handler for determining which button was
+   * clicked to close the menu. Some examples include:
+   * `"cancel"`, `"destructive"`, `"selected"`, and `"backdrop"`.
    */
   @Method()
   close(animated = true, role?: string): Promise<boolean> {
     return this.setOpen(false, animated, role);
   }
 
   /**
-   * Toggles the menu. If the menu is already open, it will try to close, otherwise it will try to open it.
+   * Toggles the menu. If the menu is already open, it will try to close,
+   * otherwise it will try to open it.
    * If the operation can't be completed successfully, it returns `false`.
+   *
+   * @param animated If `true`, the menu will animate when opening/closing.
+   * If `false`, the menu will open/close instantly without animation.
+   * Defaults to `true`.
    */
   @Method()
   toggle(animated = true): Promise<boolean> {
     return this.setOpen(!this._isOpen, animated);
   }
 
   /**
-   * Opens or closes the button.
+   * Opens or closes the menu.
    * If the operation can't be completed successfully, it returns `false`.
+   *
+   * @param shouldOpen If `true`, the menu will open. If `false`, the menu
+   * will close.
+   * @param animated If `true`, the menu will animate when opening/closing.
+   * If `false`, the menu will open/close instantly without animation.
+   * @param role The role of the element that is closing the menu.
    */
   @Method()
   setOpen(shouldOpen: boolean, animated = true, role?: string): Promise<boolean> {

core/src/components/modal/modal.tsx

@@ -739,13 +739,13 @@ export class Modal implements ComponentInterface, OverlayInterface {
 
   /**
    * Dismiss the modal overlay after it has been presented.
-   *
-   * @param data Any data to emit in the dismiss events.
-   * @param role The role of the element that is dismissing the modal. For example, 'cancel' or 'backdrop'.
-   *
    * This is a no-op if the overlay has not been presented yet. If you want
    * to remove an overlay from the DOM that was never presented, use the
    * [remove](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) method.
+   *
+   * @param data Any data to emit in the dismiss events.
+   * @param role The role of the element that is dismissing the modal.
+   * For example, `cancel` or `backdrop`.
    */
   @Method()
   async dismiss(data?: any, role?: string): Promise<boolean> {
@@ -841,8 +841,10 @@ export class Modal implements ComponentInterface, OverlayInterface {
   }
 
   /**
-   * Move a sheet style modal to a specific breakpoint. The breakpoint value must
-   * be a value defined in your `breakpoints` array.
+   * Move a sheet style modal to a specific breakpoint.
+   *
+   * @param breakpoint The breakpoint value to move the sheet modal to.
+   * Must be a value defined in your `breakpoints` array.
    */
   @Method()
   async setCurrentBreakpoint(breakpoint: number): Promise<void> {

core/src/components/popover/popover.tsx

@@ -459,6 +459,8 @@ export class Popover implements ComponentInterface, PopoverInterface {
    * Developers can pass a mouse, touch, or pointer event
    * to position the popover relative to where that event
    * was dispatched.
+   *
+   * @param event The event to position the popover relative to.
    */
   @Method()
   async present(event?: MouseEvent | TouchEvent | PointerEvent | CustomEvent): Promise<void> {
@@ -540,15 +542,14 @@ export class Popover implements ComponentInterface, PopoverInterface {
 
   /**
    * Dismiss the popover overlay after it has been presented.
+   * This is a no-op if the overlay has not been presented yet. If you want
+   * to remove an overlay from the DOM that was never presented, use the
+   * [remove](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) method.
    *
    * @param data Any data to emit in the dismiss events.
-   * @param role The role of the element that is dismissing the popover. For example, 'cancel' or 'backdrop'.
+   * @param role The role of the element that is dismissing the popover. For example, `cancel` or `backdrop`.
    * @param dismissParentPopover If `true`, dismissing this popover will also dismiss
    * a parent popover if this popover is nested. Defaults to `true`.
-   *
-   * This is a no-op if the overlay has not been presented yet. If you want
-   * to remove an overlay from the DOM that was never presented, use the
-   * [remove](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) method.
    */
   @Method()
   async dismiss(data?: any, role?: string, dismissParentPopover = true): Promise<boolean> {

core/src/components/reorder-group/reorder-group.tsx

@@ -89,7 +89,6 @@ export class ReorderGroup implements ComponentInterface {
 
   /**
    * Completes the reorder operation. Must be called by the `ionItemReorder` event.
-   *
    * If a list of items is passed, the list will be reordered and returned in the
    * proper order.
    *

core/src/components/router/router.tsx

@@ -124,6 +124,7 @@ export class Router implements ComponentInterface {
    *
    * @param path The path to navigate to.
    * @param direction The direction of the animation. Defaults to `"forward"`.
+   * @param animation A custom animation to use for the transition.
    */
   @Method()
   async push(path: string, direction: RouterDirection = 'forward', animation?: AnimationBuilder) {

core/src/components/searchbar/searchbar.tsx

@@ -302,10 +302,8 @@ export class Searchbar implements ComponentInterface {
   /**
    * Sets focus on the native `input` in `ion-searchbar`. Use this method instead of the global
    * `input.focus()`.
-   *
    * Developers who wish to focus an input when a page enters
    * should call `setFocus()` in the `ionViewDidEnter()` lifecycle method.
-   *
    * Developers who wish to focus an input when an overlay is presented
    * should call `setFocus` after `didPresent` has resolved.
    *

core/src/components/toast/toast.tsx

@@ -397,16 +397,15 @@ export class Toast implements ComponentInterface, OverlayInterface {
 
   /**
    * Dismiss the toast overlay after it has been presented.
+   * This is a no-op if the overlay has not been presented yet. If you want
+   * to remove an overlay from the DOM that was never presented, use the
+   * [remove](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) method.
    *
    * @param data Any data to emit in the dismiss events.
    * @param role The role of the element that is dismissing the toast.
    * This can be useful in a button handler for determining which button was
    * clicked to dismiss the toast.
-   * Some examples include: ``"cancel"`, `"destructive"`, "selected"`, and `"backdrop"`.
-   *
-   * This is a no-op if the overlay has not been presented yet. If you want
-   * to remove an overlay from the DOM that was never presented, use the
-   * [remove](https://developer.mozilla.org/en-US/docs/Web/API/Element/remove) method.
+   * Some examples include: `"cancel"`, `"destructive"`, `"selected"`, and `"backdrop"`.
    */
   @Method()
   async dismiss(data?: any, role?: string): Promise<boolean> {