Add documentation comments for declarative options API (#23495)

packages/grafana-data/src/panel/PanelPlugin.ts

@@ -16,8 +16,62 @@ import { deprecationWarning } from '../utils';
 import { FieldConfigOptionsRegistry, standardFieldConfigEditorRegistry } from '../field';
 import { FieldConfigOptionsRegistry, standardFieldConfigEditorRegistry } from '../field';
 
 
 export interface SetFieldConfigOptionsArgs<TFieldConfigOptions = any> {
 export interface SetFieldConfigOptionsArgs<TFieldConfigOptions = any> {
+  /**
+   * Array of standard field config properties
+   *
+   * @example
+   * ```typescript
+   * {
+   *   standardOptions: [FieldConfigProperty.Min, FieldConfigProperty.Max, FieldConfigProperty.Unit]
+   * }
+   * ```
+   */
   standardOptions?: FieldConfigProperty[];
   standardOptions?: FieldConfigProperty[];
+
+  /**
+   * Object specyfing standard option properties default values
+   *
+   * @example
+   * ```typescript
+   * {
+   *   standardOptionsDefaults: {
+   *     [FieldConfigProperty.Min]: 20,
+   *     [FieldConfigProperty.Max]: 100
+   *   }
+   * }
+   * ```
+   */
   standardOptionsDefaults?: Partial<Record<FieldConfigProperty, any>>;
   standardOptionsDefaults?: Partial<Record<FieldConfigProperty, any>>;
+
+  /**
+   * Function that allows custom field config properties definition.
+   *
+   * @param builder
+   *
+   * @example
+   * ```typescript
+   * useCustomConfig: builder => {
+   *   builder
+   *    .addNumberInput({
+   *      id: 'shapeBorderWidth',
+   *      name: 'Border width',
+   *      description: 'Border width of the shape',
+   *      settings: {
+   *        min: 1,
+   *        max: 5,
+   *      },
+   *    })
+   *    .addSelect({
+   *      id: 'displayMode',
+   *      name: 'Display mode',
+   *      description: 'How the shape shout be rendered'
+   *      settings: {
+   *      options: [{value: 'fill', label: 'Fill' }, {value: 'transparent', label: 'Transparent }]
+   *    },
+   *  })
+   * }
+   * ```
+   */
   useCustomConfig?: (builder: FieldConfigEditorBuilder<TFieldConfigOptions>) => void;
   useCustomConfig?: (builder: FieldConfigEditorBuilder<TFieldConfigOptions>) => void;
 }
 }
 
 
@@ -219,7 +273,7 @@ export class PanelPlugin<TOptions = any, TFieldConfigOptions extends object = an
    * export const plugin = new PanelPlugin<ShapePanelOptions>(ShapePanel)
    * export const plugin = new PanelPlugin<ShapePanelOptions>(ShapePanel)
    *  .useFieldConfig({
    *  .useFieldConfig({
    *    useCustomConfig: builder => {
    *    useCustomConfig: builder => {
-          builder
+   *      builder
    *       .addNumberInput({
    *       .addNumberInput({
    *         id: 'shapeBorderWidth',
    *         id: 'shapeBorderWidth',
    *         name: 'Border width',
    *         name: 'Border width',

packages/grafana-data/src/types/OptionsUIRegistryBuilder.ts

@@ -6,11 +6,40 @@ import { NumberFieldConfigSettings, SelectFieldConfigSettings, StringFieldConfig
  * Option editor registry item
  * Option editor registry item
  */
  */
 export interface OptionsEditorItem<TOptions, TSettings, TEditorProps, TValue> extends RegistryItem {
 export interface OptionsEditorItem<TOptions, TSettings, TEditorProps, TValue> extends RegistryItem {
+  /**
+   * Path of the options property to control.
+   *
+   * @example
+   * Given options object of a type:
+   * ```ts
+   * interface CustomOptions {
+   *   a: {
+   *     b: string;
+   *   }
+   * }
+   * ```
+   *
+   * path can be either 'a' or 'a.b'.
+   */
   path: (keyof TOptions & string) | string;
   path: (keyof TOptions & string) | string;
+  /**
+   * React component used to edit the options property
+   */
   editor: ComponentType<TEditorProps>;
   editor: ComponentType<TEditorProps>;
+  /**
+   * Custom settings of the editor.
+   */
   settings?: TSettings;
   settings?: TSettings;
+  /**
+   * Array of strings representing category of the options property.
+   */
   category?: string[];
   category?: string[];
   defaultValue?: TValue;
   defaultValue?: TValue;
+  /**
+   * Function that enables configuration of when option editor should be shown based on current options properties.
+   *
+   * @param currentConfig Current options values
+   */
   showIf?: (currentConfig: TOptions) => boolean;
   showIf?: (currentConfig: TOptions) => boolean;
 }
 }
 
 

packages/grafana-data/src/types/fieldOverrides.ts

@@ -54,13 +54,49 @@ export interface FieldOverrideEditorProps<TValue, TSettings> extends Omit<Standa
 }
 }
 
 
 export interface FieldConfigEditorConfig<TOptions, TSettings = any, TValue = any> {
 export interface FieldConfigEditorConfig<TOptions, TSettings = any, TValue = any> {
+  /**
+   * Path of the field config property to control.
+   *
+   * @example
+   * Given field config object of a type:
+   * ```ts
+   * interface CustomFieldConfig {
+   *   a: {
+   *     b: string;
+   *   }
+   * }
+   * ```
+   *
+   * path can be either 'a' or 'a.b'.
+   */
   path: (keyof TOptions & string) | string;
   path: (keyof TOptions & string) | string;
+  /**
+   * Name of the field config property. Will be displayed in the UI as form element label.
+   */
   name: string;
   name: string;
+  /**
+   * Description of the field config property. Will be displayed in the UI as form element description.
+   */
   description: string;
   description: string;
+  /**
+   * Array of strings representing category of the field config property. First element in the array will make option render as collapsible section.
+   */
   category?: string[];
   category?: string[];
+  /**
+   * Custom settings of the editor.
+   */
   settings?: TSettings;
   settings?: TSettings;
+  /**
+   * Funciton that allows specifying whether or not this field config shuld apply to a given field.
+   * @param field
+   */
   shouldApply?: (field: Field) => boolean;
   shouldApply?: (field: Field) => boolean;
   defaultValue?: TValue;
   defaultValue?: TValue;
+  /**
+   * Function that enables configuration of when field config property editor should be shown based on current panel field config.
+   *
+   * @param currentConfig Current field config values
+   */
   showIf?: (currentConfig: TOptions) => boolean;
   showIf?: (currentConfig: TOptions) => boolean;
 }
 }
 
 

packages/grafana-data/src/types/panel.ts

@@ -119,12 +119,44 @@ export interface PanelOptionsEditorItem<TOptions = any, TValue = any, TSettings
   extends OptionsEditorItem<TOptions, TSettings, PanelOptionsEditorProps<TValue>, TValue> {}
   extends OptionsEditorItem<TOptions, TSettings, PanelOptionsEditorProps<TValue>, TValue> {}
 
 
 export interface PanelOptionsEditorConfig<TOptions, TSettings = any, TValue = any> {
 export interface PanelOptionsEditorConfig<TOptions, TSettings = any, TValue = any> {
+  /**
+   * Path of the option property to control.
+   *
+   * @example
+   * Given options object of a type:
+   * ```ts
+   * interface Options {
+   *   a: {
+   *     b: string;
+   *   }
+   * }
+   * ```
+   *
+   * path can be either 'a' or 'a.b'.
+   */
   path: (keyof TOptions & string) | string;
   path: (keyof TOptions & string) | string;
+  /**
+   * Name of the option. Will be displayed in the UI as form element label.
+   */
   name: string;
   name: string;
+  /**
+   * Description of the option. Will be displayed in the UI as form element description.
+   */
   description: string;
   description: string;
+  /**al
+   * Custom settings of the editor.
+   */
   settings?: TSettings;
   settings?: TSettings;
+  /**
+   * Array of strings representing category of the option. First element in the array will make option render as collapsible section.
+   */
   category?: string[];
   category?: string[];
   defaultValue?: TValue;
   defaultValue?: TValue;
+  /**
+   * Function that enables configuration of when option editor should be shown based on current panel option properties.
+   *
+   * @param currentConfig Current panel options
+   */
   showIf?: (currentConfig: TOptions) => boolean;
   showIf?: (currentConfig: TOptions) => boolean;
 }
 }