@adaptabletools/adaptable 24.0.0-canary.7 → 24.0.0-canary.9

package/src/Api/AdaptableApi.d.ts

@@ -47,199 +47,203 @@ import { ColumnMenuApi } from './ColumnMenuApi';
 import { ContextMenuApi } from './ContextMenuApi';
 import { RowFormApi } from './RowFormApi';
 /**
- * Provides developers with run-time access to AdapTable.  Contains many classes each dedicated to a specific AdapTable Module or functionality
+ * Run-time access to an AdapTable instance.
+ *
+ * Each property is the API for one module. Call the module API for that module's
+ * behaviour; use `gridApi` for row data, selection and cell values, and `agGridApi`
+ * only when AdapTable does not wrap the AG Grid call.
  */
 export interface AdaptableApi {
     /**
-     * AG Grid API; try to use the API methods provided by Adaptable instead of using this directly
+     * The AG Grid API. Prefer the AdapTable APIs on this object; use this when AdapTable does not wrap the call.
      */
     agGridApi: AgGridApi;
     /**
-     * Provides access to Action Columns
+     * Action Columns and the controls they render: buttons, toggles, links, selects, commands, menus and forms.
      */
     actionColumnApi: ActionColumnApi;
     /**
-     * Provides access to the Alert Module
+     * Alert Definitions and fired alerts: add, edit, suspend, evaluate and display them.
      */
     alertApi: AlertApi;
     /**
-     * Provides access to the Application Module
+     * Application State: the key/value entries the host application stores alongside AdapTable State.
      */
     applicationApi: ApplicationApi;
     /**
-     * Provides access to the Bulk Update Module
+     * Bulk Update: the value that will be written across the selected cells.
      */
     bulkUpdateApi: BulkUpdateApi;
     /**
-     * Provides access to the Calculated Column Module
+     * Calculated Columns and the expressions that produce their values.
      */
     calculatedColumnApi: CalculatedColumnApi;
     /**
-     * Functions for managing Holidays
+     * Working days and holidays, using the weekends and holiday list in Calendar Options.
      */
     calendarApi: CalendarApi;
     /**
-     * Provides access to the Cell Summary Module
+     * The Cell Summary operation for the current selection, and its value.
      */
     cellSummaryApi: CellSummaryApi;
     /**
-     * Provides run-time access to Charting Module and state
+     * Chart Definitions, currently open charts, and the containers they are shown in.
      */
     chartingApi: ChartingApi;
     /**
-     * Provides a number of column-related methods
+     * Columns: lookup by id or friendly name, data type, and the matching AG Grid column definition.
      */
     columnApi: ColumnApi;
     /**
-     * Provides access to Column Menu
+     * The Column Menu: open it, and build its items.
      */
     columnMenuApi: ColumnMenuApi;
     /**
-     * Provides access to Context Menu
+     * The Context Menu: build its items.
      */
     contextMenuApi: ContextMenuApi;
     /**
-     * Provides access to the Comment Module
+     * Cell Comments: threads, and adding or deleting a comment.
      */
     commentApi: CommentApi;
     /**
-     * Manages the `Scope` object - used widely to determine where objects are applied
+     * Column Scope: which columns an object applies to, and whether a column is in a scope.
      */
     columnScopeApi: ColumnScopeApi;
     /**
-     * Provides access to the Custom Sort Module
+     * Custom Sorts: non-standard sort orders for a column's values.
      */
     customSortApi: CustomSortApi;
     /**
-     * Provides access to the Dashboard
+     * The Dashboard: tabs, toolbars, visibility and floating position.
      */
     dashboardApi: DashboardApi;
     /**
-     * Provides run-time access to the Data Changes Module
-     **/
+     * Data Change History: the record of cell value changes.
+     */
     dataChangeHistoryApi: DataChangeHistoryApi;
     /**
-     * Provides access to the Data Import Module
+     * Data Import. Opens the Data Import wizard.
      */
     dataImportApi: DataImportApi;
     /**
-     * Provides access to Data Sets
+     * Data Sets: the named sets of rows the grid can switch between.
      */
     dataSetApi: DataSetApi;
     /**
-     * Functions for managing Entitlements and Permissions
+     * Entitlements: the access level of each module.
      */
     entitlementApi: EntitlementApi;
     /**
-     * Used for listening / subscribing to the Events published by AdapTable
+     * AdapTable events. `on` subscribes and returns an unsubscribe function; `off` removes a listener.
      */
     eventApi: EventApi;
     /**
-     * Provides access to the Export Module and Reports
+     * Reports: run an export, and manage report definitions, formats, destinations and schedules.
      */
     exportApi: ExportApi;
     /**
-     * Manages AdapTableQL Expressions
+     * AdapTableQL expressions: validate, evaluate and open the expression editor.
      */
     expressionApi: ExpressionApi;
     /**
-     * Manages the FDC3 capabilities of AdapTable
+     * FDC3: broadcast contexts and raise intents from the grid.
      */
     fdc3Api: Fdc3Api;
     /**
-     * Provides access to Filtering in AdapTable
+     * Filtering. `columnFilterApi` is per-column filters, `gridFilterApi` is the grid filter, and `clearAllFilters` clears both.
      */
     filterApi: FilterApi;
     /**
-     * Provides access to the Flashing Cell Module
+     * Flashing Cells: which cells flash when their value changes, and in which direction.
      */
     flashingCellApi: FlashingCellApi;
     /**
-     * Provides access to the Format Column Module
+     * Format Columns: cell styles and display formats, including conditions.
      */
     formatColumnApi: FormatColumnApi;
     /**
-     * Provides access to the FreeText Column Module
+     * Free Text Columns and the text values stored against each row.
      */
     freeTextColumnApi: FreeTextColumnApi;
     /**
-     * Provides methods for managing the Grid, and Grid data, directly
+     * Grid data and selection: rows, cell values, filtering, sorting, row nodes and edited cells.
      */
     gridApi: GridApi;
     /**
-     * Provides access to the Layout Module
+     * Layouts: the current Table or Pivot Layout, and creating, selecting and extending Layouts.
      */
     layoutApi: LayoutApi;
     /**
-     * Provides access to the Named Query Module
+     * Named Queries: saved AdapTableQL queries that can be run on their own.
      */
     namedQueryApi: NamedQueryApi;
     /**
-     * Provides access to the Note Module
+     * Notes attached to cells.
      */
     noteApi: NoteApi;
     /**
-     * Provides access to Adaptable Options
+     * The Adaptable Options this instance was created with. Each getter returns one options section, read-only.
      */
     optionsApi: OptionsApi;
     /**
-     * Provides access to the Plus Minus Module
+     * Plus / Minus: the nudges that increment or decrement a numeric cell.
      */
     plusMinusApi: PlusMinusApi;
     /**
-     * Offers access to AdapTable Plugin (e.g. ipushpull, OpenFin etc)
+     * Installed plugins. `getipushpullPluginApi`, `getOpenFinPluginApi` and `getInteropioPluginApi` return the plugin API when that plugin is loaded.
      */
     pluginsApi: PluginsApi;
     /**
-     * Provides access to the Quick Search Module
+     * Quick Search: the current search text and the styles used for matches.
      */
     quickSearchApi: QuickSearchApi;
     /**
-     * Creates Row Forms
+     * Row Forms. Opens the form to create, clone or edit a row, and deletes a row by primary key.
      */
     rowFormApi: RowFormApi;
     /**
-     * Provides access to the Settings Panel
+     * The Settings Panel. Open it on a module, or on a custom settings panel.
      */
     settingsPanelApi: SettingsPanelApi;
     /**
-     * Provides access to the Shortcut Module
+     * Shortcuts: keystrokes that change a numeric cell by a fixed amount.
      */
     shortcutApi: ShortcutApi;
     /**
-     * Provides access to the Smart Edit Module
+     * Smart Edit: the arithmetic operation applied to the selected numeric cells.
      */
     smartEditApi: SmartEditApi;
     /**
-     * Methods giving access to Adaptable State
+     * AdapTable State: initial state, the full state, and the state of one module.
      */
     stateApi: StateApi;
     /**
-     * Provides run-time access to the AdapTable Status Bar
+     * The Status Bar and the AdapTable panels placed in it.
      */
     statusBarApi: StatusBarApi;
     /**
-     * Provides access to the Styled Column Module
+     * Styled Columns: gradient, percent bar, badge, bullet chart, rating, sparkline, range bar and icon styles.
      */
     styledColumnApi: StyledColumnApi;
     /**
-     * Methods related to displaying System Status and application health messages
+     * The System Status message shown in the toolbar and tool panel.
      */
     systemStatusApi: SystemStatusApi;
     /**
-     * Functions related to run-time Team Sharing of AdapTable objects between colleagues
+     * Team Sharing: objects shared between users, and importing a shared entity.
      */
     teamSharingApi: TeamSharingApi;
     /**
-     * Api methods related to Theme management
+     * Themes: the current theme, and the shipped and user themes that can be selected.
      */
     themeApi: ThemeApi;
     /**
-     * Provides access to the AdapTable Tool Panel on the right hand side of the grid
+     * The Tool Panel beside the grid, including custom tool panels.
      */
     toolPanelApi: ToolPanelApi;
     /**
-     * Manages User Interface Options where colours, styles and custom column values are configured
+     * User Interface: custom icons, editable and read-only cell styles, object tags, the progress indicator, custom windows, and showing or hiding the AdapTable UI.
      */
     userInterfaceApi: UserInterfaceApi;
     /**

package/src/Api/AlertApi.d.ts

@@ -8,7 +8,7 @@ import type { IRowNode } from 'ag-grid-enterprise';
  */
 export type AlertSettingsPanelTab = 'Alerts' | 'Alert Definitions';
 /**
- * Provides run-time access to Alert function and associated State
+ * Alert Definitions and fired alerts: read, edit, suspend, evaluate and display them.
  */
 export interface AlertApi {
     /**
@@ -23,6 +23,7 @@ export interface AlertApi {
      * `'Alert Definitions'` (the alert configuration). Pass `tab` to open a specific tab.
      * When omitted, it opens the `'Alerts'` tab if there are any live alerts, otherwise the
      * `'Alert Definitions'` tab.
+     * @param tab Tab to open. Omit it to open `'Alerts'` when live alerts exist, otherwise `'Alert Definitions'`
      */
     openAlertSettingsPanel(tab?: AlertSettingsPanelTab): void;
     /**
@@ -31,11 +32,13 @@ export interface AlertApi {
      */
     getAlertDefinitions(): AlertDefinition[];
     /**
-     * Retrieves all Alert Definitions which are currently suspended
+     * Alert Definitions that are currently suspended.
+     * @returns The suspended definitions
      */
     getSuspendedAlertDefinitions(): AlertDefinition[];
     /**
-     * Retrieves all Alert Definitions which are currently active
+     * Alert Definitions that are currently active (not suspended).
+     * @returns The active definitions
      */
     getActiveAlertDefinitions(): AlertDefinition[];
     /**
@@ -64,13 +67,13 @@ export interface AlertApi {
     editAlertDefinition(alertDefinition: AlertDefinition): AlertDefinition;
     /**
      * Deletes given Alert Definition from Adaptable State
-     * @param alertDefinition
+     * @param alertDefinition Alert Definition to delete
      */
     deleteAlertDefinition(alertDefinition: AlertDefinition): void;
     /**
      * Suspends Alert Definition
-     * @param alertDefinition Alert to suspend
-     *
+     * @param alertDefinition Alert Definition to suspend
+     * @returns The suspended Alert Definition
      */
     suspendAlertDefinition(alertDefinition: AlertDefinition): AlertDefinition;
     /**
@@ -100,11 +103,13 @@ export interface AlertApi {
      * non-live, suspended or never-evaluated definitions / rows.
      * @param alertDefinition the live Alert Definition
      * @param rowNode the row, for per-row rules
+     * @returns `'Firing'` while the rule holds, `'Normal'` when it does not, or `undefined` when the definition is not live, is suspended, or has not been evaluated
      */
     getAlertRuleState(alertDefinition: AlertDefinition, rowNode?: IRowNode): 'Normal' | 'Firing' | undefined;
     /**
      * Find all Alert Definitions which match the given criteria
-     * @param alertLookupCriteria lookup criteria
+     * @param alertLookupCriteria Ids, names or other properties to match
+     * @returns Every Alert Definition that matches
      */
     findAlertDefinitions(alertLookupCriteria: AdaptableObjectLookupCriteria): AlertDefinition[];
     /**
@@ -113,14 +118,16 @@ export interface AlertApi {
      */
     displayAdaptableAlertNotification(alert: AdaptableAlert): void;
     /**
-     * Displays the given Adaptable Alert
-     * @param alert The Alert which should be displayed
+     * Displays the given Adaptable Alert.
+     * @param alertToShow The alert to display
      */
     displayAdaptableAlert(alertToShow: AdaptableAlert): Promise<void>;
     /**
      * Creates Alert based on given parameters and displays it.
-     * @param alertHeader Header of the Alert (if shown in a popup its the Title of the Window)
+     * @param alertHeader Header of the Alert. When the alert is a popup, this is the window title
      * @param alertMessage Main message of the alert
+     * @param messageType `Success`, `Info`, `Warning` or `Error`
+     * @param alertProperties How the alert is presented: notification, popup, or both
      */
     showAlert(alertHeader: string, alertMessage: string, messageType: AdaptableMessageType, alertProperties?: AlertPresentationProperties): Promise<void>;
     /**
@@ -130,7 +137,7 @@ export interface AlertApi {
      */
     showAlertInfo(alertHeader: string, alertMessage: string): Promise<void>;
     /**
-     * Creates an Adaptable Alert based on given parameters and displays it as Succcess Alert.
+     * Creates an Adaptable Alert from the header and message and displays it as a Success alert.
      * @param alertHeader Header of the Alert (if shown in a popup its the Title of the Window)
      * @param alertMessage Main message of the alert
      */
@@ -148,7 +155,8 @@ export interface AlertApi {
      */
     showAlertError(alertHeader: string, alertMessage: string): Promise<void>;
     /**
-     * Fires a scheduled alert definition (notification, system status, etc.)
+     * Fires a scheduled Alert Definition now: its notification, system status message, or other behaviour.
+     * @param alertDefinition Scheduled Alert Definition to run
      */
     applyScheduledAlertDefinition(alertDefinition: AlertDefinition): void;
 }

package/src/Api/ApplicationApi.d.ts

@@ -4,11 +4,13 @@ import { ApplicationState, ApplicationDataEntry } from '../AdaptableState/Applic
  */
 export interface ApplicationApi {
     /**
-     * Retrieves Application section from Adaptable State
+     * The Application section of Adaptable State.
+     * @returns The current Application State
      */
     getApplicationState(): ApplicationState;
     /**
-     * Retrieves all Key Value Pairs in Application state
+     * Every key/value entry in Application State.
+     * @returns The entries, in state order
      */
     getApplicationDataEntries(): ApplicationDataEntry[];
     /**
@@ -39,12 +41,14 @@ export interface ApplicationApi {
      * Gets Application Data Entry with given key
      *
      * @param key the Key of the Application Data Entry to retrieve
+     * @returns The entry with that key, or `undefined` when no entry has it
      */
     getApplicationDataEntryByKey(key: string): ApplicationDataEntry | undefined;
     /**
      * Gets Application Data Entry with given value
      *
      * @param value the Value of the Application Data Entry to retrieve
+     * @returns Every entry whose value is `value`. Empty when none match
      */
     getApplicationDataEntriesByValue(value: any): ApplicationDataEntry[];
 }

package/src/Api/BulkUpdateApi.d.ts

@@ -3,7 +3,8 @@
  **/
 export interface BulkUpdateApi {
     /**
-     * Returns current Bulk Update value
+     * The value Bulk Update will write into the selected cells.
+     * @returns The current Bulk Update value. Empty when none has been entered
      */
     getBulkUpdateValue(): string;
     /**

package/src/Api/CalculatedColumnApi.d.ts

@@ -1,18 +1,21 @@
 import { CalculatedColumn, CalculatedColumnState } from '../AdaptableState/CalculatedColumnState';
 /**
- * Provides run-time access to the Calculated Column Module
+ * Calculated Columns, whose values come from an AdapTableQL expression.
  **/
 export interface CalculatedColumnApi {
     /**
      * Retrieves Calculated Column section from Adaptable State
+     * @returns Calculated Column section from Adaptable State
      */
     getCalculatedColumnState(): CalculatedColumnState;
     /**
      * Retrieves all Calculated Columns in Adaptable State
+     * @returns All Calculated Columns in Adaptable State
      */
     getCalculatedColumns(): CalculatedColumn[];
     /**
      * Retrieves all Aggregated Calculated Columns in Adaptable State
+     * @returns All Aggregated Calculated Columns in Adaptable State
      */
     getAggregatedCalculatedColumns(): CalculatedColumn[];
     /**

package/src/Api/CalendarApi.d.ts

@@ -9,55 +9,65 @@ export interface CalendarApi {
      * Returns the next working day after `from` (defaults to today).
      * Never returns `from` itself.
      * @param from Optional start date (defaults to today)
+     * @returns The next working day after `from` (defaults to today). Never returns `from` itself
      */
     getNextWorkingDay(from?: Date): Date;
     /**
      * Returns the previous working day before `from` (defaults to today).
      * Never returns `from` itself.
      * @param from Optional start date (defaults to today)
+     * @returns The previous working day before `from` (defaults to today). Never returns `from` itself
      */
     getPreviousWorkingDay(from?: Date): Date;
     /**
      * True when the date is neither a weekend day nor a configured holiday.
      * @param dateToCheck Date to check
+     * @returns True when the date is neither a weekend day nor a configured holiday
      */
     isWorkingDay(dateToCheck: Date): boolean;
     /**
      * True when the date is in the configured holiday list.
      * Weekends are not holidays unless also listed in `calendarOptions.holidays`.
      * @param dateToCheck Date to check
+     * @returns True when the date is in the configured holiday list. Weekends are not holidays unless also listed in `calendarOptions.holidays`
      */
     isHoliday(dateToCheck: Date): boolean;
     /**
      * True when the date falls on a configured weekend day
      * (`calendarOptions.weekendDays`, default Saturday/Sunday).
      * @param dateToCheck Date to check
+     * @returns True when the date falls on a configured weekend day (`calendarOptions.weekendDays`, default Saturday/Sunday)
      */
     isWeekend(dateToCheck: Date): boolean;
     /**
      * First day of the week for week-number / start-of-week Expression Functions
      * (`calendarOptions.weekStartsOn`, default `0` = Sunday).
+     * @returns First day of the week for week-number / start-of-week Expression Functions (`calendarOptions.weekStartsOn`, default `0` = Sunday)
      */
     getWeekStartsOn(): number;
     /**
      * Returns true if both dates are the same calendar day (time ignored).
      * @param date1 1st Date
      * @param date2 2nd Date
+     * @returns `true` when both dates are the same calendar day (time ignored)
      */
     isSameDay(date1: Date, date2: Date): boolean;
     /**
      * Returns true if the given date is today
      * @param dateToCheck Date to Check
+     * @returns `true` when the given date is today
      */
     isToday(dateToCheck: Date): boolean;
     /**
      * Returns true if the given date is yesterday
      * @param dateToCheck Date to Check
+     * @returns `true` when the given date is yesterday
      */
     isYesterday(dateToCheck: Date): boolean;
     /**
      * Returns true if the given date is tomorrow
      * @param dateToCheck Date to Check
+     * @returns `true` when the given date is tomorrow
      */
     isTomorrow(dateToCheck: Date): boolean;
 }

package/src/Api/CellSummaryApi.d.ts

@@ -1,18 +1,21 @@
 import { CustomCellSummaryOperation } from '../AdaptableState/Common/CellSummary';
 /**
- *  Provides run-time access to the Cell Summary Module
+ * The summary calculated for the selected cells, such as sum or average, and the value it produces.
  */
 export interface CellSummaryApi {
     /**
      * Retrieves all Custom Cell Summary Operations
+     * @returns All Custom Cell Summary Operations
      */
     getCustomCellSummaryOperations(): CustomCellSummaryOperation[];
     /**
      * Retrieves currently selected Cell Summary Operation
+     * @returns Currently selected Cell Summary Operation
      */
     getCurrentCellSummaryOperation(): CustomCellSummaryOperation | string;
     /**
-     * Sets the currently selected Cell Summary Operation
+     * Selects which summary to show for the current cell selection.
+     * @param operation Operation name, or a custom operation
      */
     setCurrentCellSummaryOperation(operation: CustomCellSummaryOperation | string): void;
     /**
@@ -21,10 +24,13 @@ export interface CellSummaryApi {
     openCellSummaryPopupSettingsPanel(): void;
     /**
      * Retrieves the value of the current selected Cell Summary Operation
+     * @returns The value of the current selected Cell Summary Operation
      */
     getCurrentCellSummaryOperationValue(): number;
     /**
-     * Retrieves the value of the given Cell Summary Operation
+     * The result of a summary operation for the current selection.
+     * @param operation Operation to evaluate
+     * @returns The result of a summary operation for the current selection
      */
     getCellSummaryOperationValue(operation: CustomCellSummaryOperation | string): any;
 }

package/src/Api/ChartingApi.d.ts

@@ -3,41 +3,50 @@ import { ExternalChartDefinition } from '../AdaptableState/ChartingState';
 import { ChartContainer, ChartDefinition } from '../types';
 import { ChartingOpenState } from './Events/ChartChanged';
 /**
- * Provides run-time access to Charting Module and related State
+ * Charts saved in AdapTable, and external chart definitions. Includes which charts are open.
  */
 export interface ChartingApi {
     /**
      * Whether AdapTable's Charting functionality is available
+     * @returns `true` when AdapTable's Charting functionality is available
      */
     isChartingEnabled(): boolean;
     /**
      * Retrieves current user-generated Charts
+     * @returns Current user-generated Charts
      */
     getCurrentChartModels(): ChartModel[];
     /**
      * Retrieves persisted Charts from Adaptable State
+     * @returns Persisted Charts from Adaptable State
      */
     getPersistedCharts(): ChartModel[];
     /**
      * Retrieves all adaptable Chart definitions
+     * @returns All adaptable Chart definitions
      */
     getChartDefinitions(): ChartDefinition[];
     /**
      * Retrieves all adaptable external Chart definitions
+     * @returns All adaptable external Chart definitions
      */
     getExternalChartDefinitions(): ExternalChartDefinition[];
     /**
      * Retrieves Chart definition by uuid
      * @param uuid Chart uuid
+     * @returns Chart definition by uuid
      */
     getChartDefinitionByUuid(uuid: string): ChartDefinition | undefined;
     /**
      * Retrieves Chart definition by name
      * @param name Chart name
+     * @returns Chart definition by name
      */
     getChartDefinitionByName(name: string): ChartDefinition | undefined;
     /**
-     * Retrieves AG Grid ChartRef for given ChartId
+     * The AG Grid chart reference for a chart AdapTable has open.
+     * @param chartId Id of the chart
+     * @returns The AG Grid chart reference for a chart AdapTable has open
      */
     getChartRef(chartId: string): ChartRef | undefined;
     /**
@@ -46,6 +55,7 @@ export interface ChartingApi {
     saveCurrentCharts(): void;
     /**
      * Displays all persisted Charts
+     * @returns The chart references for the charts that were opened
      */
     showPersistedCharts(): ChartRef[];
     /**
@@ -53,6 +63,7 @@ export interface ChartingApi {
      *
      * @param chartDefinition Chart Definition
      * @param container container element or container name
+     * @returns The chart reference for the chart that was opened
      */
     showChartDefinition(chartDefinition: ChartDefinition, container?: HTMLElement | string): ChartRef;
     /**
@@ -64,6 +75,7 @@ export interface ChartingApi {
      * Displays a Chart; if Chart is already open, 2nd Chart is not opened
      * @param chartDefinition Chart to show
      * @param container Container in which to display the Chart
+     * @returns The chart reference. When the chart is already open, that chart is returned and another is not opened
      */
     showChartDefinitionOnce(chartDefinition: ChartDefinition, container?: HTMLElement | string): ChartRef | undefined;
     /**
@@ -88,19 +100,21 @@ export interface ChartingApi {
     addChartDefinition(chartDefinition: ChartDefinition): void;
     /**
      * Get info about all saved charts, incl. their open state
+     * @returns Info about all saved charts, incl. their open state
      */
     getChartingOpenState(): ChartingOpenState;
     /**
      * Retrieve name of container in which Chart is open; returns null if Chart is not open
-     * @param chartDefinition Chart to add
+     * @param chartDefinition Chart to look up
+     * @returns Retrieve name of container in which Chart is open; returns null if Chart is not open
      */
     getOpenChartContainer(chartDefinition: ChartDefinition): ChartContainer | null;
     /**
      * Add new external chart definition
      *
      * @param chartDef external chart definition
-     * @param options
-     * @param options.saveChartBehaviour whether to ask the user to provide a name for the chart
+     * @param options How the chart is saved. Omit it to use the default
+     * @param options.saveChartBehaviour `'manual'` asks for a name. `'auto'` saves without asking
      */
     addExternalChartDefinition(chartDef: ExternalChartDefinition, options?: {
         saveChartBehaviour: 'auto' | 'manual';
@@ -116,8 +130,9 @@ export interface ChartingApi {
      */
     deleteExternalChartDefinition(chartDefinition: ExternalChartDefinition): void;
     /**
-     * Retrieves Chart definition by name
-     * @param name Chart name
+     * An external chart definition looked up by name.
+     * @param name Name of the external chart
+     * @returns An external chart definition looked up by name
      */
     getExternalChartDefinitionByName(name: string): ExternalChartDefinition | undefined;
 }