From 4b7bb418daad4abd28c29dfe0b14f8dfda521d09 Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Tue, 13 Apr 2021 13:07:40 +0200 Subject: [PATCH] Docs: fix export issue to prevent docs generation from failing. (#32929) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fixing docs generation issue. * jsdoc fixes * raised limit Co-authored-by: Torkel Ödegaard --- .../src/themes/colorManipulator.ts | 72 +++++++++++-------- packages/grafana-data/src/themes/index.ts | 13 +++- packages/grafana-data/src/types/dataFrame.ts | 7 ++ scripts/ci-reference-docs-lint.sh | 2 +- 4 files changed, 62 insertions(+), 32 deletions(-) diff --git a/packages/grafana-data/src/themes/colorManipulator.ts b/packages/grafana-data/src/themes/colorManipulator.ts index 11f50007370..0b76bbc6875 100644 --- a/packages/grafana-data/src/themes/colorManipulator.ts +++ b/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); diff --git a/packages/grafana-data/src/themes/index.ts b/packages/grafana-data/src/themes/index.ts index 556dcb78acf..ec2d483c1e9 100644 --- a/packages/grafana-data/src/themes/index.ts +++ b/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 }; diff --git a/packages/grafana-data/src/types/dataFrame.ts b/packages/grafana-data/src/types/dataFrame.ts index 154d64a9888..3b055ba84d9 100644 --- a/packages/grafana-data/src/types/dataFrame.ts +++ b/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 { custom?: TOptions; } +/** @public */ export interface ValueLinkConfig { /** * Result of field reduction @@ -134,6 +137,7 @@ export interface Field> { getLinks?: (config: ValueLinkConfig) => Array>; } +/** @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 { @@ -197,6 +203,7 @@ export interface FieldDTO { } /** + * @public * Like a DataFrame, but fields may be a FieldDTO */ export interface DataFrameDTO extends QueryResultBase { diff --git a/scripts/ci-reference-docs-lint.sh b/scripts/ci-reference-docs-lint.sh index b035de09323..00db95f2039 100755 --- a/scripts/ci-reference-docs-lint.sh +++ b/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"