docs: better docs and types for the API (#7796)

* docs: fix type imports in openmct.js

* docs: fix type imports

* docs: fix types for eventHelpers

* docs: types for TypeRegistry

* docs: types for StatusAPI

* docs: fix ObjectAPI types and docs

* docs: more types

* docs: improved types for main entry

* docs: improved types

* fix: unbreak the linting

* chore: remove EventEmitter webpack alias as it hide types

* fix: return type

* fix: parameter type

* fix: types for composables

* chore: add webpack consts to eslintrc

* fix: remove usage of deprecated timeAPI methods and add a ton of docs and types

* docs: update README.md

* lint: clean up API.md

* chore: upgrade eventemitter to v5.0.2

* refactor: update imports for EventEmitter to remove alias

* format: lint

* docs: update types for Views and ViewProviders

* docs: expose common types at the base import level

* docs(types): remove unnecessary tsconfig options

* docs: ActionAPI

* docs: AnnotationAPI

* docs: import common types from the same origin

* docs: FormsAPI & TelemetryAPI types

* docs: FormController, IndicatorAPI

* docs: MenuAPI, ActionsAPI

* docs: `@memberof` is not supported by `tsc` and JSDoc generation so remove it

* docs: RootRegistry and RootObjectProvider

* docs: Transaction + Overlay

* lint: words for the word god

* fix: review comments

src/plugins/DeviceClassifier/src/DeviceMatchers.js

@@ -28,7 +28,6 @@
  *
  * For internal use by the mobile support bundle.
  *
- * @memberof src/plugins/DeviceClassifier
  * @private
  */
 

src/plugins/LADTable/LADTableConfiguration.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import { markRaw } from 'vue';
 export default class LADTableConfiguration extends EventEmitter {
   constructor(domainObject, openmct) {

src/plugins/activityStates/activityStatesInterceptor.js

@@ -24,7 +24,7 @@ import { ACTIVITY_STATES_KEY } from './createActivityStatesIdentifier.js';
 
 /**
  * @typedef {Object} ActivityStatesInterceptorOptions
- * @property {import('../../api/objects/ObjectAPI').Identifier} identifier the {namespace, key} to use for the activity states object.
+ * @property {import('openmct').Identifier} identifier the {namespace, key} to use for the activity states object.
  * @property {string} name The name of the activity states model.
  * @property {number} priority the priority of the interceptor. By default, it is low.
  */

src/plugins/charts/bar/pluginSpec.js

@@ -21,7 +21,7 @@
  *****************************************************************************/
 
 // import BarGraph from './BarGraphPlot.vue';
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import { createOpenMct, resetApplicationState } from 'utils/testing';
 import { nextTick } from 'vue';
 

src/plugins/charts/scatter/pluginSpec.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import { createOpenMct, resetApplicationState } from 'utils/testing';
 import { nextTick } from 'vue';
 

src/plugins/clock/pluginSpec.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import { createOpenMct, resetApplicationState } from 'utils/testing';
 import { nextTick } from 'vue';
 

src/plugins/condition/Condition.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import { v4 as uuid } from 'uuid';
 
 import AllTelemetryCriterion from './criterion/AllTelemetryCriterion.js';

src/plugins/condition/ConditionManager.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import { v4 as uuid } from 'uuid';
 
 import Condition from './Condition.js';

src/plugins/condition/StyleRuleManager.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 export default class StyleRuleManager extends EventEmitter {
   constructor(styleConfiguration, openmct, callback, suppressSubscriptionOnEdit) {

src/plugins/condition/criterion/TelemetryCriterion.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 import StalenessUtils from '@/utils/staleness';
 

src/plugins/displayLayout/LayoutDrag.js

@@ -45,7 +45,6 @@
  * @param {number[]} dimFactor the dimensions factor
  * @param {number[]} the size of each grid element, in pixels
  * @constructor
- * @memberof platform/features/layout
  */
 export default function LayoutDrag(rawPosition, posFactor, dimFactor, gridSize) {
   this.rawPosition = rawPosition;

src/plugins/exportAsJSONAction/ExportAsJSONAction.js

@@ -108,7 +108,7 @@ class ExportAsJSONAction {
 
   /**
    * @private
-   * @param {import('../../api/objects/ObjectAPI').DomainObject} parent
+   * @param {import('openmct').DomainObject} parent
    */
   async #write(parent) {
     this.totalToExport++;

src/plugins/flexibleLayout/pluginSpec.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import { createOpenMct, resetApplicationState } from 'utils/testing';
 import { nextTick } from 'vue';
 

src/plugins/imagery/lib/eventHelpers.js

@@ -20,6 +20,9 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
+/**
+ * @type {EventHelpers}
+ */
 const helperFunctions = {
   listenTo: function (object, event, callback, context) {
     if (!this._listeningTo) {
@@ -95,3 +98,8 @@ const helperFunctions = {
 };
 
 export default helperFunctions;
+/**
+ * @typedef {Object} EventHelpers
+ * @property {(object: any, event: string, callback: Function, context?: any) => void} listenTo
+ * @property {(object: any, event?: string, callback?: Function, context?: any) => void} stopListening
+ */

src/plugins/inspectorViews/styles/StylesManager.js

@@ -1,4 +1,4 @@
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 const LOCAL_STORAGE_KEY = 'mct-saved-styles';
 const LIMIT = 20;

src/plugins/localTimeSystem/LocalTimeFormat.js

@@ -38,7 +38,6 @@ const DATE_FORMATS = [DATE_FORMAT, 'YYYY-MM-DD h:mm:ss a', 'YYYY-MM-DD h:mm a',
  *
  * @implements {Format}
  * @constructor
- * @memberof platform/commonUI/formats
  */
 export default function LocalTimeFormat() {
   this.key = 'local-format';

src/plugins/localTimeSystem/pluginSpec.js

@@ -61,7 +61,7 @@ describe('The local time', () => {
     });
 
     it('can be set to be the main time system', () => {
-      expect(openmct.time.timeSystem().key).toBe(LOCAL_SYSTEM_KEY);
+      expect(openmct.time.getTimeSystem().key).toBe(LOCAL_SYSTEM_KEY);
     });
 
     it('uses the local-format time format', () => {

src/plugins/notebook/snapshot-container.js

@@ -1,4 +1,4 @@
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 import { EVENT_SNAPSHOTS_UPDATED } from './notebook-constants.js';
 const NOTEBOOK_SNAPSHOT_STORAGE = 'notebook-snapshot-storage';

src/plugins/persistence/couch/CouchDocument.js

@@ -27,7 +27,6 @@
  * metadata field which contains a subset of information found
  * in the model itself (to support search optimization with
  * CouchDB views.)
- * @memberof platform/persistence/couch
  * @constructor
  * @param {string} id the id under which to store this mode
  * @param {Object} model the model to store

src/plugins/plan/PlanViewConfiguration.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 export const DEFAULT_CONFIGURATION = {
   clipActivityNames: false,

src/plugins/plan/inspector/components/PlanViewConfiguration.vue

@@ -77,7 +77,7 @@ export default {
   inject: ['openmct'],
   data() {
     const selection = this.openmct.selection.get();
-    /** @type {import('../../../api/objects/ObjectAPI').DomainObject}  */
+    /** @type {import('openmct').DomainObject}  */
     const domainObject = selection[0][0].context.item;
     const planViewConfiguration = markRaw(new PlanViewConfiguration(domainObject, this.openmct));
 

src/plugins/plot/configuration/Model.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'eventemitter3';
+import { EventEmitter } from 'eventemitter3';
 import _ from 'lodash';
 
 import eventHelpers from '../lib/eventHelpers.js';

src/plugins/plot/configuration/PlotConfigurationModel.js

@@ -126,7 +126,7 @@ export default class PlotConfigurationModel extends Model {
   }
   /**
    * Retrieve the persisted series config for a given identifier.
-   * @param {import('./PlotSeries').Identifier} identifier
+   * @param {import('openmct').Identifier} identifier
    * @returns {import('./PlotSeries').PlotSeriesModelType=}
    */
   getPersistedSeriesConfig(identifier) {

src/plugins/plot/draw/Draw2D.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 import eventHelpers from '../lib/eventHelpers.js';
 import { MARKER_SHAPES } from './MarkerShapes.js';
@@ -138,5 +138,4 @@ class Draw2D extends EventEmitter {
     }
   }
 }
-
 export default Draw2D;

src/plugins/plot/draw/DrawWebGL.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 import eventHelpers from '../lib/eventHelpers.js';
 import { MARKER_SHAPES } from './MarkerShapes.js';
@@ -297,5 +297,4 @@ class DrawWebGL extends EventEmitter {
     }
   }
 }
-
 export default DrawWebGL;

src/plugins/plot/lib/eventHelpers.js

@@ -19,8 +19,10 @@
  * this source code distribution or the Licensing information page available
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
-/*jscs:disable disallowDanglingUnderscores */
 
+/**
+ * @type {EventHelpers}
+ */
 const helperFunctions = {
   listenTo: function (object, event, callback, context) {
     if (!this._listeningTo) {
@@ -94,7 +96,7 @@ export default helperFunctions;
 
 /**
 @typedef {{
-    listenTo: (object: any, event: any, callback: any, context: any) => void
+    listenTo: (object: any, event: any, callback: any, context: any) => void,
     stopListening: (object: any, event: any, callback: any, context: any) => void
 }} EventHelpers
 */

src/plugins/plot/overlayPlot/pluginSpec.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import mount from 'utils/mount';
 import {
   createMouseEvent,

src/plugins/plot/pluginSpec.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import mount from 'utils/mount';
 import {
   createMouseEvent,

src/plugins/plot/stackedPlot/pluginSpec.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import mount from 'utils/mount';
 import {
   createMouseEvent,

src/plugins/plugins.js

@@ -87,6 +87,9 @@ import ViewDatumAction from './viewDatumAction/plugin.js';
 import ViewLargeAction from './viewLargeAction/plugin.js';
 import WebPagePlugin from './webPage/plugin.js';
 
+/**
+ * @type {Object}
+ */
 const plugins = {};
 
 plugins.example = {};

src/plugins/remoteClock/RemoteClock.js

@@ -149,8 +149,6 @@ export default class RemoteClock extends DefaultClock {
 
   /**
    * Waits for the clock to have a non-default tick value.
-   *
-   * @private
    */
   #waitForReady() {
     const waitForInitialTick = (resolve) => {

src/plugins/summaryWidget/src/Condition.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 import * as templateHelpers from '../../../utils/template/templateHelpers.js';
 import conditionTemplate from '../res/conditionTemplate.html';

src/plugins/summaryWidget/src/ConditionManager.js

@@ -1,4 +1,4 @@
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import _ from 'lodash';
 import { makeKeyString } from 'objectUtils';
 

src/plugins/summaryWidget/src/Rule.js

@@ -1,4 +1,4 @@
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import _ from 'lodash';
 
 import * as templateHelpers from '../../../utils/template/templateHelpers.js';

src/plugins/summaryWidget/src/TestDataItem.js

@@ -1,4 +1,4 @@
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 import * as templateHelpers from '../../../utils/template/templateHelpers.js';
 import itemTemplate from '../res/testDataItemTemplate.html';

src/plugins/summaryWidget/src/WidgetDnD.js

@@ -1,4 +1,4 @@
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 import * as templateHelpers from '../../../utils/template/templateHelpers.js';
 import ruleImageTemplate from '../res/ruleImageTemplate.html';

src/plugins/summaryWidget/src/input/Palette.js

@@ -1,4 +1,4 @@
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 import * as templateHelpers from '../../../../utils/template/templateHelpers.js';
 import paletteTemplate from '../../res/input/paletteTemplate.html';

src/plugins/summaryWidget/src/input/Select.js

@@ -1,4 +1,4 @@
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 
 import * as templateHelpers from '../../../../utils/template/templateHelpers.js';
 import selectTemplate from '../../res/input/selectTemplate.html';

src/plugins/tabs/pluginSpec.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import { createOpenMct, resetApplicationState } from 'utils/testing';
 import { nextTick } from 'vue';
 

src/plugins/telemetryMean/src/MeanTelemetryProviderSpec.js

@@ -611,7 +611,7 @@ describe('The Mean Telemetry Provider', function () {
   }
 
   function createMockTimeApi() {
-    return jasmine.createSpyObj('timeApi', ['getTimeSystem']);
+    return jasmine.createSpyObj('timeApi', ['getTimeSystem', 'setTimeSystem']);
   }
 
   function setTimeSystemTo(timeSystemKey) {

src/plugins/telemetryTable/TelemetryTable.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import _ from 'lodash';
 
 import StalenessUtils from '../../utils/staleness.js';

src/plugins/telemetryTable/TelemetryTableConfiguration.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import _ from 'lodash';
 
 export default class TelemetryTableConfiguration extends EventEmitter {

src/plugins/telemetryTable/collections/TableRowCollection.js

@@ -19,7 +19,7 @@
  * this source code distribution or the Licensing information page available
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import _ from 'lodash';
 
 /**

src/plugins/timeline/pluginSpec.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import { nextTick } from 'vue';
 
 import { createOpenMct, resetApplicationState } from '@/utils/testing';

src/plugins/timelist/pluginSpec.js

@@ -20,7 +20,7 @@
  * at runtime from the About dialog for additional information.
  *****************************************************************************/
 
-import EventEmitter from 'EventEmitter';
+import { EventEmitter } from 'eventemitter3';
 import { createOpenMct, resetApplicationState } from 'utils/testing';
 import { nextTick } from 'vue';
 

src/plugins/timer/plugin.js

@@ -26,6 +26,7 @@ import StartTimerAction from './actions/StartTimerAction.js';
 import StopTimerAction from './actions/StopTimerAction.js';
 import TimerViewProvider from './TimerViewProvider.js';
 
+/** @type {OpenMCTPlugin} */
 export default function TimerPlugin() {
   return function install(openmct) {
     openmct.types.addType('timer', {

src/plugins/utcTimeSystem/DurationFormat.js

@@ -12,7 +12,6 @@ const DATE_FORMATS = [DATE_FORMAT];
  *
  * @implements {Format}
  * @constructor
- * @memberof platform/commonUI/formats
  */
 class DurationFormat {
   constructor() {

src/plugins/utcTimeSystem/UTCTimeFormat.js

@@ -28,7 +28,6 @@ import moment from 'moment';
  *
  * @implements {Format}
  * @constructor
- * @memberof platform/commonUI/formats
  */
 export default class UTCTimeFormat {
   constructor() {