diff --git a/packages/grafana-ui/src/types/panel.ts b/packages/grafana-ui/src/types/panel.ts
index da0d399fe65..d66fa601a29 100644
--- a/packages/grafana-ui/src/types/panel.ts
+++ b/packages/grafana-ui/src/types/panel.ts
@@ -27,10 +27,15 @@ export interface PanelEditorProps<T = any> {
 }
 
 /**
- * Checks the existing model before the component is loaded
- * This is useful for fixing options as configuration changes
- * The object passed in is the panel model.... but not typed
- * since that is not in grafana ui
+ * This function is called with the full panelModel before
+ * the pluginPanel is constructed.  This gives you an opportunity
+ * to validate the panel settings before the panel loads.
+ *
+ * @param panelModel the whole panel object.  including the configuration
+ * saved for other panels
+ *
+ * @returns the validated panel options that will be passed into the
+ * panel constructor
  */
 export type PanelOptionsValidator<T = any> = (panelModel: any) => T;
 
diff --git a/public/app/features/dashboard/dashgrid/DashboardPanel.tsx b/public/app/features/dashboard/dashgrid/DashboardPanel.tsx
index fb2b2ab6471..faefa97a74e 100644
--- a/public/app/features/dashboard/dashgrid/DashboardPanel.tsx
+++ b/public/app/features/dashboard/dashgrid/DashboardPanel.tsx
@@ -96,7 +96,8 @@ export class DashboardPanel extends PureComponent<Props, State> {
     }
   }
 
-  // This is be called before the plugin constructor, so the initial properties are valid
+  // This is called before the plugin is added to the three,
+  // it allows plugins to update options before loading
   validateOptions = (plugin: PanelPlugin, panel: PanelModel) => {
     const { reactPanel } = plugin.exports;
     if (reactPanel && reactPanel.optionsValidator) {