Docs: fix export issue to prevent docs generation from failing. (#32929)

* fixing docs generation issue.

* jsdoc fixes

* raised limit

Co-authored-by: Torkel Ödegaard <torkel@grafana.com>

packages/grafana-data/src/themes/colorManipulator.ts

@@ -4,10 +4,11 @@
 
 /**
  * Returns a number whose value is limited to the given range.
- * @param {number} value The value to be clamped
- * @param {number} min The lower boundary of the output range
- * @param {number} max The upper boundary of the output range
- * @returns {number} A number in the range [min, max]
+ * @param value The value to be clamped
+ * @param min The lower boundary of the output range
+ * @param max The upper boundary of the output range
+ * @returns A number in the range [min, max]
+ * @beta
  */
 function clamp(value: number, min = 0, max = 1) {
   if (process.env.NODE_ENV !== 'production') {
@@ -21,8 +22,9 @@ function clamp(value: number, min = 0, max = 1) {
 
 /**
  * Converts a color from CSS hex format to CSS rgb format.
- * @param {string} color - Hex color, i.e. #nnn or #nnnnnn
- * @returns {string} A CSS rgb color string
+ * @param color - Hex color, i.e. #nnn or #nnnnnn
+ * @returns A CSS rgb color string
+ * @beta
  */
 export function hexToRgb(color: string) {
   color = color.substr(1);
@@ -50,8 +52,9 @@ function intToHex(int: number) {
 
 /**
  * Converts a color from CSS rgb format to CSS hex format.
- * @param {string} color - RGB color, i.e. rgb(n, n, n)
- * @returns {string} A CSS rgb color string, i.e. #nnnnnn
+ * @param color - RGB color, i.e. rgb(n, n, n)
+ * @returns A CSS rgb color string, i.e. #nnnnnn
+ * @beta
  */
 export function rgbToHex(color: string) {
   // Idempotent
@@ -65,8 +68,9 @@ export function rgbToHex(color: string) {
 
 /**
  * Converts a color from hsl format to rgb format.
- * @param {string} color - HSL color values
- * @returns {string} rgb color values
+ * @param color - HSL color values
+ * @returns rgb color values
+ * @beta
  */
 export function hslToRgb(color: string | DecomposeColor) {
   const parts = decomposeColor(color);
@@ -92,8 +96,9 @@ export function hslToRgb(color: string | DecomposeColor) {
  * Returns an object with the type and values of a color.
  *
  * Note: Does not support rgb % values.
- * @param {string} color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla()
+ * @param color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla()
  * @returns {object} - A MUI color object: {type: string, values: number[]}
+ * @beta
  */
 export function decomposeColor(color: string | DecomposeColor): DecomposeColor {
   // Idempotent
@@ -139,9 +144,10 @@ export function decomposeColor(color: string | DecomposeColor): DecomposeColor {
 /**
  * Converts a color object with type and values to a string.
  * @param {object} color - Decomposed color
- * @param {string} color.type - One of: 'rgb', 'rgba', 'hsl', 'hsla'
+ * @param color.type - One of: 'rgb', 'rgba', 'hsl', 'hsla'
  * @param {array} color.values - [n,n,n] or [n,n,n,n]
- * @returns {string} A CSS color string
+ * @returns A CSS color string
+ * @beta
  */
 export function recomposeColor(color: DecomposeColor) {
   const { type, colorSpace } = color;
@@ -167,9 +173,10 @@ export function recomposeColor(color: DecomposeColor) {
  * Calculates the contrast ratio between two colors.
  *
  * Formula: https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests
- * @param {string} foreground - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla()
- * @param {string} background - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla()
- * @returns {number} A contrast ratio value in the range 0 - 21.
+ * @param foreground - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla()
+ * @param background - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla()
+ * @returns A contrast ratio value in the range 0 - 21.
+ * @beta
  */
 export function getContrastRatio(foreground: string, background: string) {
   const lumA = getLuminance(foreground);
@@ -182,8 +189,9 @@ export function getContrastRatio(foreground: string, background: string) {
  * normalized to 0 for darkest black and 1 for lightest white.
  *
  * Formula: https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests
- * @param {string} color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color()
- * @returns {number} The relative brightness of the color in the range 0 - 1
+ * @param color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color()
+ * @returns The relative brightness of the color in the range 0 - 1
+ * @beta
  */
 export function getLuminance(color: string) {
   const parts = decomposeColor(color);
@@ -203,9 +211,10 @@ export function getLuminance(color: string) {
 /**
  * Darken or lighten a color, depending on its luminance.
  * Light colors are darkened, dark colors are lightened.
- * @param {string} color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color()
- * @param {number} coefficient=0.15 - multiplier in the range 0 - 1
- * @returns {string} A CSS color string. Hex input values are returned as rgb
+ * @param color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color()
+ * @param coefficient=0.15 - multiplier in the range 0 - 1
+ * @returns A CSS color string. Hex input values are returned as rgb
+ * @beta
  */
 export function emphasize(color: string, coefficient = 0.15) {
   return getLuminance(color) > 0.5 ? darken(color, coefficient) : lighten(color, coefficient);
@@ -214,9 +223,10 @@ export function emphasize(color: string, coefficient = 0.15) {
 /**
  * Set the absolute transparency of a color.
  * Any existing alpha values are overwritten.
- * @param {string} color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color()
- * @param {number} value - value to set the alpha channel to in the range 0 - 1
- * @returns {string} A CSS color string. Hex input values are returned as rgb
+ * @param color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color()
+ * @param value - value to set the alpha channel to in the range 0 - 1
+ * @returns A CSS color string. Hex input values are returned as rgb
+ * @beta
  */
 export function alpha(color: string, value: number) {
   const parts = decomposeColor(color);
@@ -236,9 +246,10 @@ export function alpha(color: string, value: number) {
 
 /**
  * Darkens a color.
- * @param {string} color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color()
- * @param {number} coefficient - multiplier in the range 0 - 1
- * @returns {string} A CSS color string. Hex input values are returned as rgb
+ * @param color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color()
+ * @param coefficient - multiplier in the range 0 - 1
+ * @returns A CSS color string. Hex input values are returned as rgb
+ * @beta
  */
 export function darken(color: string, coefficient: number) {
   const parts = decomposeColor(color);
@@ -256,9 +267,10 @@ export function darken(color: string, coefficient: number) {
 
 /**
  * Lightens a color.
- * @param {string} color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color()
- * @param {number} coefficient - multiplier in the range 0 - 1
- * @returns {string} A CSS color string. Hex input values are returned as rgb
+ * @param color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(), hsl(), hsla(), color()
+ * @param coefficient - multiplier in the range 0 - 1
+ * @returns A CSS color string. Hex input values are returned as rgb
+ * @beta
  */
 export function lighten(color: string, coefficient: number) {
   const parts = decomposeColor(color);

packages/grafana-data/src/themes/index.ts

@@ -1,3 +1,14 @@
 export { createTheme, GrafanaThemeV2 } from './createTheme';
 export { ThemePaletteColor } from './types';
-export * as colorManipulator from './colorManipulator';
+export { ThemePalette } from './createPalette';
+export { ThemeBreakpoints } from './breakpoints';
+export { ThemeShadows } from './createShadows';
+export { ThemeShape } from './createShape';
+export { ThemeTypography } from './createTypography';
+export { ThemeTransitions } from './createTransitions';
+export { ThemeSpacing } from './createSpacing';
+export { ThemeZIndices } from './zIndex';
+
+/** Exporting the module like this to be able to generate docs properly. */
+import * as colorManipulator from './colorManipulator';
+export { colorManipulator };

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

@@ -7,6 +7,7 @@ import { Vector } from './vector';
 import { FieldColor } from './fieldColor';
 import { ScopedVars } from './ScopedVars';
 
+/** @public */
 export enum FieldType {
   time = 'time', // or date
   number = 'number',
@@ -18,6 +19,7 @@ export enum FieldType {
 }
 
 /**
+ * @public
  * Every property is optional
  *
  * Plugins may extend this with additional properties. Something like series overrides
@@ -86,6 +88,7 @@ export interface FieldConfig<TOptions extends object = any> {
   custom?: TOptions;
 }
 
+/** @public */
 export interface ValueLinkConfig {
   /**
    * Result of field reduction
@@ -134,6 +137,7 @@ export interface Field<T = any, V = Vector<T>> {
   getLinks?: (config: ValueLinkConfig) => Array<LinkModel<Field>>;
 }
 
+/** @alpha */
 export interface FieldState {
   /**
    * An appropriate name for the field (does not include frame info)
@@ -171,6 +175,7 @@ export interface FieldState {
   origin?: DataFrameFieldIndex;
 }
 
+/** @public */
 export interface NumericRange {
   min?: number | null;
   max?: number | null;
@@ -186,6 +191,7 @@ export interface DataFrame extends QueryResultBase {
 }
 
 /**
+ * @public
  * Like a field, but properties are optional and values may be a simple array
  */
 export interface FieldDTO<T = any> {
@@ -197,6 +203,7 @@ export interface FieldDTO<T = any> {
 }
 
 /**
+ * @public
  * Like a DataFrame, but fields may be a FieldDTO
  */
 export interface DataFrameDTO extends QueryResultBase {

scripts/ci-reference-docs-lint.sh

@@ -29,7 +29,7 @@ if [ ! -d "$REPORT_PATH" ]; then
 fi
 
 WARNINGS_COUNT="$(find "$REPORT_PATH" -type f -name \*.log -print0 | xargs -0 grep -o "Warning: " | wc -l | xargs)"
-WARNINGS_COUNT_LIMIT=1061
+WARNINGS_COUNT_LIMIT=1071
 
 if [ "$WARNINGS_COUNT" -gt $WARNINGS_COUNT_LIMIT ]; then
   echo -e "API Extractor warnings/errors $WARNINGS_COUNT exceeded $WARNINGS_COUNT_LIMIT so failing build.\n"