Add comments to some alerting plugin public API items

api_docs/alerting.json

@@ -5,7 +5,42 @@
     "functions": [],
     "interfaces": [],
     "enums": [],
-    "misc": [],
+    "misc": [
+      {
+        "parentPluginId": "alerting",
+        "id": "def-public.AlertNavigationHandler",
+        "type": "Type",
+        "tags": [],
+        "label": "AlertNavigationHandler",
+        "description": [
+          "\nReturns information that can be used to navigate to a specific page to view the given rule.\n"
+        ],
+        "signature": [
+          "(alert: Pick<",
+          {
+            "pluginId": "alerting",
+            "scope": "common",
+            "docId": "kibAlertingPluginApi",
+            "section": "def-common.Alert",
+            "text": "Alert"
+          },
+          "<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">) => string | ",
+          {
+            "pluginId": "kibanaUtils",
+            "scope": "common",
+            "docId": "kibKibanaUtilsPluginApi",
+            "section": "def-common.JsonObject",
+            "text": "JsonObject"
+          }
+        ],
+        "source": {
+          "path": "x-pack/plugins/alerting/public/alert_navigation_registry/types.ts",
+          "lineNumber": 20
+        },
+        "deprecated": false,
+        "initialIsOpen": false
+      }
+    ],
     "objects": [],
     "setup": {
       "parentPluginId": "alerting",
@@ -24,44 +59,58 @@
           "parentPluginId": "alerting",
           "id": "def-public.PluginSetupContract.registerNavigation",
           "type": "Function",
-          "tags": [],
+          "tags": [
+            "throws"
+          ],
           "label": "registerNavigation",
-          "description": [],
+          "description": [
+            "\nRegister a customized view of the particular rule type. Stack Management provides a generic overview, but a developer can register a\ncustom navigation to provide the user an extra link to a more curated view. The alerting plugin doesn't actually do\nanything with this information, but it can be used by other plugins via the `getNavigation` functionality. Currently\nthe trigger_actions_ui plugin uses it to expose the link from the generic rule view in Stack Management.\n"
+          ],
           "signature": [
-            "(consumer: string, alertType: string, handler: ",
-            "AlertNavigationHandler",
+            "(applicationId: string, ruleType: string, handler: ",
+            {
+              "pluginId": "alerting",
+              "scope": "public",
+              "docId": "kibAlertingPluginApi",
+              "section": "def-public.AlertNavigationHandler",
+              "text": "AlertNavigationHandler"
+            },
             ") => void"
           ],
           "source": {
             "path": "x-pack/plugins/alerting/public/plugin.ts",
-            "lineNumber": 15
+            "lineNumber": 30
           },
           "deprecated": false,
           "returnComment": [],
           "children": [
             {
               "parentPluginId": "alerting",
-              "id": "def-public.consumer",
+              "id": "def-public.applicationId",
               "type": "string",
               "tags": [],
-              "label": "consumer",
-              "description": [],
+              "label": "applicationId",
+              "description": [
+                "The application id that the user should be navigated to, to view a particular alert in a custom way."
+              ],
               "source": {
                 "path": "x-pack/plugins/alerting/public/plugin.ts",
-                "lineNumber": 16
+                "lineNumber": 31
               },
               "deprecated": false
             },
             {
               "parentPluginId": "alerting",
-              "id": "def-public.alertType",
+              "id": "def-public.ruleType",
               "type": "string",
               "tags": [],
-              "label": "alertType",
-              "description": [],
+              "label": "ruleType",
+              "description": [
+                "The rule type that has been registered with Alerting.Server.PluginSetupContract.registerType. If\nno such rule with that id exists, a warning is output to the console log. It used to throw an error, but that was temporarily moved\nbecause it was causing flaky test failures with https://github.com/elastic/kibana/issues/59229 and needs to be\ninvestigated more."
+              ],
               "source": {
                 "path": "x-pack/plugins/alerting/public/plugin.ts",
-                "lineNumber": 17
+                "lineNumber": 32
               },
               "deprecated": false
             },
@@ -71,7 +120,9 @@
               "type": "Function",
               "tags": [],
               "label": "handler",
-              "description": [],
+              "description": [
+                "The navigation handler should return either a relative URL, or a state object. This information can be used,\nin conjunction with the consumer id, to navigate the user to a custom URL to view a rule's details."
+              ],
               "signature": [
                 "(alert: Pick<",
                 {
@@ -81,15 +132,7 @@
                   "section": "def-common.Alert",
                   "text": "Alert"
                 },
-                "<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">, alertType: ",
-                {
-                  "pluginId": "alerting",
-                  "scope": "common",
-                  "docId": "kibAlertingPluginApi",
-                  "section": "def-common.AlertType",
-                  "text": "AlertType"
-                },
-                "<\"default\", \"recovered\">) => string | ",
+                "<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">) => string | ",
                 {
                   "pluginId": "kibanaUtils",
                   "scope": "common",
@@ -100,7 +143,7 @@
               ],
               "source": {
                 "path": "x-pack/plugins/alerting/public/plugin.ts",
-                "lineNumber": 18
+                "lineNumber": 33
               },
               "deprecated": false
             }
@@ -112,29 +155,39 @@
           "type": "Function",
           "tags": [],
           "label": "registerDefaultNavigation",
-          "description": [],
+          "description": [
+            "\nRegister a customized view for all rule types. Stack Management provides a generic overview, but a developer can register a\ncustom navigation to provide the user an extra link to a more curated view. The alerting plugin doesn't actually do\nanything with this information, but it can be used by other plugins via the `getNavigation` functionality. Currently\nthe trigger_actions_ui plugin uses it to expose the link from the generic rule view in Stack Management.\n"
+          ],
           "signature": [
-            "(consumer: string, handler: ",
-            "AlertNavigationHandler",
+            "(applicationId: string, handler: ",
+            {
+              "pluginId": "alerting",
+              "scope": "public",
+              "docId": "kibAlertingPluginApi",
+              "section": "def-public.AlertNavigationHandler",
+              "text": "AlertNavigationHandler"
+            },
             ") => void"
           ],
           "source": {
             "path": "x-pack/plugins/alerting/public/plugin.ts",
-            "lineNumber": 20
+            "lineNumber": 46
           },
           "deprecated": false,
           "returnComment": [],
           "children": [
             {
               "parentPluginId": "alerting",
-              "id": "def-public.consumer",
+              "id": "def-public.applicationId",
               "type": "string",
               "tags": [],
-              "label": "consumer",
-              "description": [],
+              "label": "applicationId",
+              "description": [
+                "The application id that the user should be navigated to, to view a particular alert in a custom way."
+              ],
               "source": {
                 "path": "x-pack/plugins/alerting/public/plugin.ts",
-                "lineNumber": 20
+                "lineNumber": 46
               },
               "deprecated": false
             },
@@ -144,7 +197,9 @@
               "type": "Function",
               "tags": [],
               "label": "handler",
-              "description": [],
+              "description": [
+                "The navigation handler should return either a relative URL, or a state object. This information can be used,\nin conjunction with the consumer id, to navigate the user to a custom URL to view a rule's details."
+              ],
               "signature": [
                 "(alert: Pick<",
                 {
@@ -154,15 +209,7 @@
                   "section": "def-common.Alert",
                   "text": "Alert"
                 },
-                "<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">, alertType: ",
-                {
-                  "pluginId": "alerting",
-                  "scope": "common",
-                  "docId": "kibAlertingPluginApi",
-                  "section": "def-common.AlertType",
-                  "text": "AlertType"
-                },
-                "<\"default\", \"recovered\">) => string | ",
+                "<never>, \"enabled\" | \"id\" | \"name\" | \"params\" | \"actions\" | \"tags\" | \"alertTypeId\" | \"consumer\" | \"schedule\" | \"scheduledTaskId\" | \"createdBy\" | \"updatedBy\" | \"createdAt\" | \"updatedAt\" | \"apiKeyOwner\" | \"throttle\" | \"notifyWhen\" | \"muteAll\" | \"mutedInstanceIds\" | \"executionStatus\">) => string | ",
                 {
                   "pluginId": "kibanaUtils",
                   "scope": "common",
@@ -173,7 +220,7 @@
               ],
               "source": {
                 "path": "x-pack/plugins/alerting/public/plugin.ts",
-                "lineNumber": 20
+                "lineNumber": 46
               },
               "deprecated": false
             }
@@ -192,7 +239,7 @@
       "description": [],
       "source": {
         "path": "x-pack/plugins/alerting/public/plugin.ts",
-        "lineNumber": 22
+        "lineNumber": 48
       },
       "deprecated": false,
       "children": [
@@ -224,7 +271,7 @@
           ],
           "source": {
             "path": "x-pack/plugins/alerting/public/plugin.ts",
-            "lineNumber": 23
+            "lineNumber": 49
           },
           "deprecated": false,
           "returnComment": [],
@@ -238,7 +285,7 @@
               "description": [],
               "source": {
                 "path": "x-pack/plugins/alerting/public/plugin.ts",
-                "lineNumber": 23
+                "lineNumber": 49
               },
               "deprecated": false
             }
@@ -3857,7 +3904,7 @@
         "label": "ReservedActionGroups",
         "description": [],
         "signature": [
-          "\"recovered\" | RecoveryActionGroupId"
+          "RecoveryActionGroupId | \"recovered\""
         ],
         "source": {
           "path": "x-pack/plugins/alerting/common/builtin_action_groups.ts",

api_docs/alerting.mdx

@@ -29,6 +29,9 @@ import alertingObj from './alerting.json';
 ### Start
 <DocDefinitionList data={[alertingObj.client.start]}/>
 
+### Consts, variables and types
+<DocDefinitionList data={alertingObj.client.misc}/>
+
 ## Server
 
 ### Functions

x-pack/plugins/alerting/README.md

@@ -619,7 +619,7 @@ The _registerNavigation_ api allows you to register a handler for a specific ale
 alerting.registerNavigation(
 	'my-application-id',
 	'my-application-id.my-rule-type',
-	(alert: SanitizedAlert, alertType: AlertType) => `/my-unique-rule/${rule.id}`
+	(alert: SanitizedAlert) => `/my-unique-rule/${rule.id}`
 );
 ```
 
@@ -635,7 +635,7 @@ The _registerDefaultNavigation_ API allows you to register a handler for any rul
 ```
 alerting.registerDefaultNavigation(
 	'my-application-id',
-	(alert: SanitizedAlert, alertType: AlertType) => `/my-other-rules/${rule.id}`
+	(alert: SanitizedAlert) => `/my-other-rules/${rule.id}`
 );
 ```
 

x-pack/plugins/alerting/public/alert_navigation_registry/alert_navigation_registry.test.ts

@@ -23,7 +23,7 @@ const mockAlertType = (id: string): AlertType => ({
 });
 
 describe('AlertNavigationRegistry', () => {
-  function handler(alert: SanitizedAlert, alertType: AlertType) {
+  function handler(alert: SanitizedAlert) {
     return {};
   }
 
@@ -143,7 +143,7 @@ describe('AlertNavigationRegistry', () => {
     test('returns registered handlers by consumer & Alert Type', () => {
       const registry = new AlertNavigationRegistry();
 
-      function indexThresholdHandler(alert: SanitizedAlert, alertType: AlertType) {
+      function indexThresholdHandler(alert: SanitizedAlert) {
         return {};
       }
 
@@ -155,7 +155,7 @@ describe('AlertNavigationRegistry', () => {
     test('returns default handlers by consumer when there is no handler for requested alert type', () => {
       const registry = new AlertNavigationRegistry();
 
-      function defaultHandler(alert: SanitizedAlert, alertType: AlertType) {
+      function defaultHandler(alert: SanitizedAlert) {
         return {};
       }
 
@@ -168,7 +168,7 @@ describe('AlertNavigationRegistry', () => {
 
       registry.register('siem', mockAlertType('indexThreshold'), () => ({}));
 
-      function defaultHandler(alert: SanitizedAlert, alertType: AlertType) {
+      function defaultHandler(alert: SanitizedAlert) {
         return {};
       }
 

x-pack/plugins/alerting/public/alert_navigation_registry/types.ts

@@ -6,9 +6,15 @@
  */
 
 import { JsonObject } from '../../../../../src/plugins/kibana_utils/common';
-import { AlertType, SanitizedAlert } from '../../common';
+import { SanitizedAlert } from '../../common';
 
-export type AlertNavigationHandler = (
-  alert: SanitizedAlert,
-  alertType: AlertType
-) => JsonObject | string;
+/**
+ * Returns information that can be used to navigate to a specific page to view the given rule.
+ *
+ * @param rule The rule to view
+ * @returns A URL that is meant to be relative to your application id, or a state object that your application uses to render
+ * the rule. This information is intended to be used with cores NavigateToApp function, along with the application id that was
+ * originally registered to {@link PluginSetupContract.registerNavigation}.
+ *
+ */
+export type AlertNavigationHandler = (alert: SanitizedAlert) => JsonObject | string;

x-pack/plugins/alerting/public/index.ts

@@ -6,7 +6,8 @@
  */
 
 import { AlertingPublicPlugin } from './plugin';
-export { PluginSetupContract, PluginStartContract } from './plugin';
+export type { PluginSetupContract, PluginStartContract } from './plugin';
+export type { AlertNavigationHandler } from './alert_navigation_registry';
 
 export function plugin() {
   return new AlertingPublicPlugin();