docs: ensure that optionality matches between documented params and signatures (#18613)

* docs: ensure that optionality matches between documented params and signatures

* docs: ensure that all optional declarations are lower case

* chore: fix broken link

docs/api/app.md

@@ -576,7 +576,7 @@ Hides all application windows without minimizing them.
 Shows application windows after they were hidden. Does not automatically focus
 them.
 
-### `app.setAppLogsPath(path)`
+### `app.setAppLogsPath([path])`
 
 * `path` String (optional) - A custom path for your logs. Must be absolute.
 

docs/api/browser-window.md

@@ -864,7 +864,7 @@ Returns `Boolean` - Whether the window is in normal state (not maximized, not mi
 
 * `aspectRatio` Float - The aspect ratio to maintain for some portion of the
 content view.
-* `extraSize` [Size](structures/size.md) - The extra size not to be included while
+* `extraSize` [Size](structures/size.md) (optional) - The extra size not to be included while
 maintaining the aspect ratio.
 
 This will make a window maintain an aspect ratio. The extra size allows a

docs/api/content-tracing.md

@@ -52,7 +52,7 @@ as soon as they receive the EnableRecording request.
 If a recording is already running, the promise will be immediately resolved, as
 only one trace operation can be in progress at a time.
 
-### `contentTracing.stopRecording(resultFilePath)`
+### `contentTracing.stopRecording([resultFilePath])`
 
 * `resultFilePath` String (optional)
 

docs/api/in-app-purchase.md

@@ -21,7 +21,7 @@ Returns:
 
 The `inAppPurchase` module has the following methods:
 
-### `inAppPurchase.purchaseProduct(productID, quantity)`
+### `inAppPurchase.purchaseProduct(productID[, quantity])`
 
 * `productID` String - The identifiers of the product to purchase. (The identifier of `com.example.app.product1` is `product1`).
 * `quantity` Integer (optional) - The number of items the user wants to purchase.

docs/api/ipc-main.md

@@ -84,7 +84,7 @@ Removes the specified `listener` from the listener array for the specified
 
 ### `ipcMain.removeAllListeners([channel])`
 
-* `channel` String
+* `channel` String (optional)
 
 Removes listeners of the specified `channel`.
 

docs/api/ipc-renderer.md

@@ -51,7 +51,7 @@ Removes the specified `listener` from the listener array for the specified
 
 Removes all listeners, or those of the specified `channel`.
 
-### `ipcRenderer.send(channel[, arg1][, arg2][, ...])`
+### `ipcRenderer.send(channel, ...args)`
 
 * `channel` String
 * `...args` any[]
@@ -63,7 +63,7 @@ hence no functions or prototype chain will be included.
 The main process handles it by listening for `channel` with the
 [`ipcMain`](ipc-main.md) module.
 
-### `ipcRenderer.invoke(channel[, arg1][, arg2][, ...])`
+### `ipcRenderer.invoke(channel, ...args)`
 
 * `channel` String
 * `...args` any[]
@@ -91,7 +91,7 @@ ipcMain.handle('some-name', async (event, someArgument) => {
 })
 ```
 
-### `ipcRenderer.sendSync(channel[, arg1][, arg2][, ...])`
+### `ipcRenderer.sendSync(channel, ...args)`
 
 * `channel` String
 * `...args` any[]
@@ -108,7 +108,7 @@ and replies by setting `event.returnValue`.
 **Note:** Sending a synchronous message will block the whole renderer process,
 unless you know what you are doing you should never use it.
 
-### `ipcRenderer.sendTo(webContentsId, channel, [, arg1][, arg2][, ...])`
+### `ipcRenderer.sendTo(webContentsId, channel, ...args)`
 
 * `webContentsId` Number
 * `channel` String
@@ -116,7 +116,7 @@ unless you know what you are doing you should never use it.
 
 Sends a message to a window with `webContentsId` via `channel`.
 
-### `ipcRenderer.sendToHost(channel[, arg1][, arg2][, ...])`
+### `ipcRenderer.sendToHost(channel, ...args)`
 
 * `channel` String
 * `...args` any[]

docs/api/menu.md

@@ -65,7 +65,7 @@ You can also attach other fields to the element of the `template` and they will
 
 The `menu` object has the following instance methods:
 
-#### `menu.popup(options)`
+#### `menu.popup([options])`
 
 * `options` Object (optional)
   * `window` [BrowserWindow](browser-window.md) (optional) - Default is the focused window.

docs/api/native-image.md

@@ -172,7 +172,7 @@ Creates a new `NativeImage` instance from `dataURL`.
 ### `nativeImage.createFromNamedImage(imageName[, hslShift])` _macOS_
 
 * `imageName` String
-* `hslShift` Number[]
+* `hslShift` Number[] (optional)
 
 Returns `NativeImage`
 

docs/api/notification.md

@@ -29,7 +29,7 @@ Returns `Boolean` - Whether or not desktop notifications are supported on the cu
 
 ### `new Notification([options])` _Experimental_
 
-* `options` Object
+* `options` Object (optional)
   * `title` String - A title for the notification, which will be shown at the top of the notification window when it is shown.
   * `subtitle` String (optional) _macOS_ - A subtitle for the notification, which will be displayed below the title.
   * `body` String - The body text of the notification, which will be displayed below the title or subtitle.

docs/api/web-contents.md

@@ -1396,7 +1396,7 @@ Opens the developer tools for the shared worker context.
 
 Opens the developer tools for the service worker context.
 
-#### `contents.send(channel[, arg1][, arg2][, ...])`
+#### `contents.send(channel, ...args)`
 
 * `channel` String
 * `...args` any[]
@@ -1437,7 +1437,7 @@ app.on('ready', () => {
 </html>
 ```
 
-#### `contents.sendToFrame(frameId, channel[, arg1][, arg2][, ...])`
+#### `contents.sendToFrame(frameId, channel, ...args)`
 
 * `frameId` Integer
 * `channel` String

docs/api/web-request.md

@@ -131,7 +131,7 @@ response are visible by the time this listener is fired.
     * `timestamp` Double
     * `statusLine` String
     * `statusCode` Integer
-    * `responseHeaders` Record<string, string> (Optional)
+    * `responseHeaders` Record<string, string> (optional)
   * `callback` Function
     * `response` Object
       * `cancel` Boolean (optional)
@@ -160,7 +160,7 @@ The `callback` has to be called with an `response` object.
     * `resourceType` String
     * `referrer` String
     * `timestamp` Double
-    * `responseHeaders` Record<string, string> (Optional)
+    * `responseHeaders` Record<string, string> (optional)
     * `fromCache` Boolean - Indicates whether the response was fetched from disk
       cache.
     * `statusCode` Integer
@@ -189,7 +189,7 @@ and response headers are available.
     * `ip` String (optional) - The server IP address that the request was
       actually sent to.
     * `fromCache` Boolean
-    * `responseHeaders` Record<string, string> (Optional)
+    * `responseHeaders` Record<string, string> (optional)
 
 The `listener` will be called with `listener(details)` when a server initiated
 redirect is about to occur.
@@ -208,7 +208,7 @@ redirect is about to occur.
     * `resourceType` String
     * `referrer` String
     * `timestamp` Double
-    * `responseHeaders` Record<string, string> (Optional)
+    * `responseHeaders` Record<string, string> (optional)
     * `fromCache` Boolean
     * `statusCode` Integer
     * `statusLine` String

docs/api/webview-tag.md

@@ -557,7 +557,7 @@ Returns `Promise<NativeImage>` - Resolves with a [NativeImage](native-image.md)
 
 Captures a snapshot of the page within `rect`. Omitting `rect` will capture the whole visible page.
 
-### `<webview>.send(channel[, arg1][, arg2][, ...])`
+### `<webview>.send(channel, ...args)`
 
 * `channel` String
 * `...args` any[]
@@ -566,7 +566,7 @@ Send an asynchronous message to renderer process via `channel`, you can also
 send arbitrary arguments. The renderer process can handle the message by
 listening to the `channel` event with the [`ipcRenderer`](ipc-renderer.md) module.
 
-See [webContents.send](web-contents.md#contentssendchannel-arg1-arg2-) for
+See [webContents.send](web-contents.md#contentssendchannel-args) for
 examples.
 
 ### `<webview>.sendInputEvent(event)`