diff --git a/build/generate-docs.ts b/build/generate-docs.ts index d56f96adf..98e88be42 100644 --- a/build/generate-docs.ts +++ b/build/generate-docs.ts @@ -4,7 +4,7 @@ import {formatJSON} from './util'; /** * This script generates markdown documentation from the JSON schema. - * It leverages exitsing md files in the docs folder and adds generated files from the v8.json file. + * It leverages existing md files in the docs folder and adds generated files from the v8.json file. */ const BASE_PATH = 'docs'; @@ -12,15 +12,20 @@ const BASE_PATH = 'docs'; type JsonExpressionSyntax = { overloads: { parameters: string[]; - 'output-type': string; - }[]; - parameters?: { - name: string; - type: string; - doc?: string; + 'output-type': string | string[]; }[]; + parameters?: Parameter[]; } +type Parameter ={ + name: string; + type: ParameterType; + doc?: string; +}; + +// either a basic type, a union of a few basic types or an object +type ParameterType = string | string[] | { [key: string]: JsonObject }; + type JsonSdkSupport = { [info: string]: { js?: string; @@ -36,10 +41,13 @@ type JsonObject = { type: string; doc: string; requires?: any[]; - example: string | object | number; + example: string | object | number | boolean; expression?: { interpolated?: boolean; parameters?: string[]}; transition?: boolean; + // for enum type: what is the type of the emum elements values?: {[key: string]: { doc: string; 'sdk-support'?: JsonSdkSupport }} | number[]; + // for array type: what is the type of the array elements? + value?: string; minimum?: number; maximum?: number; } @@ -121,6 +129,52 @@ function sdkSupportToMarkdown(support: JsonSdkSupport): string { return markdown; } +/** + * Joins the array of type strings into a single string with `" | "` between them. + * @param input the array or string to be joined + * @returns the joined string + */ +function parameterTypeToType(input: ParameterType):string{ + if ( typeof input === 'string' ) + return input + if (Array.isArray(input)) { + return input.join(' | ') + } + const parameters = Object.entries(input) + .map(([key, val])=> { + const requiredSuffix = val.required ? '' : '?'; + return `${key}${requiredSuffix}: ${jsonObjectToType(val)}` + }) + .join(', ') + + return `{${parameters}}`; +} + +/** + * Converts the JSON object to a type string. + * @param val - the JSON object + * @returns the type string + */ +function jsonObjectToType(val: JsonObject):string{ + switch (val.type) { + case 'boolean': + case 'string': + case 'number': + case 'color': + // basic types -> no conversion needed + return val.type + case 'array': + return `${val.type}<${parameterTypeToType(val.value)}>`; + case 'enum': + const values = val.values; + if (!values || Array.isArray(values)) + throw new Error(`Enum ${JSON.stringify(val)} has no "values" describing the contained Options in the form of an Object`) + return Object.keys(values).map(s=>`"${s}"`).join(' | '); + default: + throw new Error(`Unknown "type" ${val.type} for ${JSON.stringify(val)}`) + } +} + /** * Converts the expression syntax object to markdown format. * @param key - the expression name @@ -130,17 +184,32 @@ function sdkSupportToMarkdown(support: JsonSdkSupport): string { function expressionSyntaxToMarkdown(key: string, syntax: JsonExpressionSyntax) { let markdown = '\nSyntax:\n'; const codeBlockLines = syntax.overloads.map((overload) => { - return `[${[`"${key}"`, ...overload.parameters].join(', ')}]: ${overload['output-type']}`; + const key_and_parameters = [`"${key}"`, ...overload.parameters].join(', '); + + return `[${key_and_parameters}]: ${parameterTypeToType(overload['output-type'])}`; }); markdown += `${codeBlockMarkdown(codeBlockLines.join('\n'), 'js')}\n`; for (const parameter of syntax.parameters ?? []) { - markdown += `- \`${parameter.name}\``; - if (parameter.type) { - const type = parameter.type.replaceAll('<', '<').replaceAll('>', '>'); - markdown += `: *${type}*`; - } + const type = parameterTypeToType(parameter.type).replaceAll('<', '<').replaceAll('>', '>'); + markdown += `- \`${parameter.name}\`: \`${type}\``; if (parameter.doc) { - markdown += ` — ${parameter.doc}`; + markdown += `- ${parameter.doc}`; + } + if (typeof parameter.type !== 'string' && !Array.isArray(parameter.type)){ + // the type is an object type => we can attach more documentation about the contained variables + markdown += ' \nParameters:' + Object.entries(parameter.type).forEach(([key, val])=>{ + const type = jsonObjectToType(val).replaceAll('<', '<').replaceAll('>', '>'); + markdown += `\n - \`${key}\`: \`${type}\` - ${val.doc}` + if (val.type==='enum' && val.values){ + markdown += ' \n Possible values are:' + for (const [enumKey, enumValue] of Object.entries(val.values)) { + const defaultIndicator = val.default === enumKey ? ' *default*' : ''; + markdown += `\n - \`"${enumKey}"\`${defaultIndicator} - ${enumValue.doc}` + } + } + + }) } markdown += '\n'; } diff --git a/src/reference/v8.json b/src/reference/v8.json index 31878e487..80f6af539 100644 --- a/src/reference/v8.json +++ b/src/reference/v8.json @@ -3053,7 +3053,7 @@ }, { "name": "type", - "type": "\"string\" | \"number\" | \"boolean\"", + "type": ["string", "number", "boolean"], "doc": "The asserted type of the input array." }, { @@ -3295,12 +3295,12 @@ "parameters": [ { "name": "input", - "type": "string | number", + "type": ["string", "number"], "doc": "Any expression." }, { "name": "label_i", - "type": "string literal | number literal | array | array", + "type": ["string literal", "number literal", "array", "array"], "doc": "The i-th literal value or array of literal values to match the input against." }, { @@ -3399,13 +3399,13 @@ "overloads": [ { "parameters": ["interpolation_type", "input", "stop_1_input", "stop_1_output", "...", "stop_n_input", "stop_n_output"], - "output-type": "number | array | color | array | projection" + "output-type": ["number", "array", "color", "array", "projection"] } ], "parameters": [ { "name": "interpolation_type", - "type": "[\"linear\"] | [\"exponential\", base] | [\"cubic-bezier\", x1, y1, x2, y2]", + "type": ["[\"linear\"]", "[\"exponential\", base]", "[\"cubic-bezier\", x1, y1, x2, y2]"], "doc": "The interpolation type." }, { @@ -3420,7 +3420,7 @@ }, { "name": "stop_i_output", - "type": "number | array | color | array | projection", + "type": ["number", "array", "color", "array", "projection"], "doc": "The output value corresponding to the i-th stop." } ] @@ -3441,13 +3441,13 @@ "overloads": [ { "parameters": ["interpolation_type", "input", "stop_1_input", "stop_1_output", "...", "stop_n_input", "stop_n_output"], - "output-type": "color | array" + "output-type": ["color", "array"] } ], "parameters": [ { "name": "interpolation_type", - "type": "[\"linear\"] | [\"exponential\", base] | [\"cubic-bezier\", x1, y1, x2, y2]" + "type": ["[\"linear\"]", "[\"exponential\", base]", "[\"cubic-bezier\", x1, y1, x2, y2]"] }, { "name": "input", @@ -3459,7 +3459,7 @@ }, { "name": "stop_i_output", - "type": "color | array" + "type": ["color", "array"] } ] }, @@ -3479,13 +3479,13 @@ "overloads": [ { "parameters": ["interpolation_type", "input", "stop_1_input", "stop_1_output", "...", "stop_n_input", "stop_n_output"], - "output-type": "color | array" + "output-type": ["color", "array"] } ], "parameters": [ { "name": "interpolation_type", - "type": "[\"linear\"] | [\"exponential\", base] | [\"cubic-bezier\", x1, y1, x2, y2]" + "type": ["[\"linear\"]", "[\"exponential\", base]", "[\"cubic-bezier\", x1, y1, x2, y2]"] }, { "name": "input", @@ -3497,7 +3497,7 @@ }, { "name": "stop_i_output", - "type": "color | array" + "type": ["color", "array"] } ] }, @@ -3702,7 +3702,7 @@ } }, "collator": { - "doc": "Returns a `collator` for use in locale-dependent comparison operations. The `case-sensitive` and `diacritic-sensitive` options default to `false`. The `locale` argument specifies the IETF language tag of the locale to use. If none is provided, the default locale is used. If the requested locale is not available, the `collator` will use a system-defined fallback locale. Use `resolved-locale` to test the results of locale fallback behavior.", + "doc": "Returns a `collator` for use in locale-dependent comparison operations. Use `resolved-locale` to test the results of locale fallback behavior.", "syntax": { "overloads": [ { @@ -3713,7 +3713,25 @@ "parameters": [ { "name": "options", - "type": "{ \"case-sensitive\"?: boolean, \"diacritic-sensitive\"?: boolean, \"locale\"?: string }" + "type": { + "case-sensitive": { + "type": "boolean", + "default": false, + "example": true, + "doc": "If characters of different case-ness are considered different" + }, + "diacritic-sensitive": { + "type": "boolean", + "default": false, + "example": true, + "doc": "If characters with different diacritics are considered different" + }, + "locale": { + "type": "string", + "example": "en", + "doc": "IETF language tag of the locale to use. If none is provided, the default locale is used. If the requested locale is not available, the `collator` will use a system-defined fallback locale." + } + } } ] }, @@ -3728,7 +3746,7 @@ } }, "format": { - "doc": "Returns a `formatted` string for displaying mixed-format text in the `text-field` property. The input may contain a string literal or expression, including an [`'image'`](#image) expression. Strings may be followed by a style override object that supports the following properties:\n\n- `\"text-font\"`: Overrides the font stack specified by the root layout property.\n\n- `\"text-color\"`: Overrides the color specified by the root paint property.\n\n- `\"font-scale\"`: Applies a scaling factor on `text-size` as specified by the root layout property.\n\n- `\"vertical-align\"`: Aligns vertically text section or image in relation to the row it belongs to. Possible values are: \n\t- `\"bottom\"` *default*: align the bottom of this section with the bottom of other sections.\n\"Visual\n\t- `\"center\"`: align the center of this section with the center of other sections.\n\"Visual\n\t- `\"top\"`: align the top of this section with the top of other sections.\n\"Visual\n\t- Refer to [the design proposal](https://github.com/maplibre/maplibre-style-spec/issues/832) for more details.\n\n - [Change the case of labels](https://maplibre.org/maplibre-gl-js/docs/examples/change-case-of-labels/)\n\n - [Display and style rich text labels](https://maplibre.org/maplibre-gl-js/docs/examples/display-and-style-rich-text-labels/)", + "doc": "Returns a `formatted` string for displaying mixed-format text in the `text-field` property. The input may contain a string literal or expression, including an [`'image'`](#image) expression. Strings may be followed by a style override object.\n\n - [Change the case of labels](https://maplibre.org/maplibre-gl-js/docs/examples/change-case-of-labels/)\n\n - [Display and style rich text labels](https://maplibre.org/maplibre-gl-js/docs/examples/display-and-style-rich-text-labels/)", "syntax": { "overloads": [ { @@ -3739,11 +3757,44 @@ "parameters": [ { "name": "input_i", - "type": "string | image" + "type": ["string", "image"] }, { "name": "style_overrides_i", - "type": "{ \"text-font\"?: string, \"text-color\"?: color, \"font-scale\"?: number, \"vertical-align\"?: \"bottom\" | \"center\" | \"top\" }" + "type": { + "text-font": { + "type": "string", + "doc": "Overrides the font stack specified by the root layout property.", + "example": "Arial Unicode MS Regular" + }, + "text-color": { + "type": "color", + "doc": "Overrides the color specified by the root paint property.", + "example": "#333" + }, + "font-scale": { + "type": "number", + "doc":"Applies a scaling factor on `text-size` as specified by the root layout property.", + "example": 1.2 + }, + "vertical-align": { + "type": "enum", + "doc": "Aligns a vertical text section or image in relation to the row it belongs to. Refer to [the design proposal](https://github.com/maplibre/maplibre-style-spec/issues/832) for more details.", + "default": "bottom", + "example": "bottom", + "values": { + "bottom": { + "doc": "align the bottom of this section with the bottom of other sections.\n![Visual representation of bottom alignment](https://github.com/user-attachments/assets/0474a2fd-a4b2-417c-9187-7a13a28695bc)" + }, + "center": { + "doc": "align the center of this section with the center of other sections.\n![Visual representation of center alignment](https://github.com/user-attachments/assets/92237455-be6d-4c5d-b8f6-8127effc1950)" + }, + "top": { + "doc": "align the top of this section with the top of other sections.\n![Visual representation of top alignment](https://github.com/user-attachments/assets/45dccb28-d977-4abb-a006-4ea9792b7c53)" + } + } + } + } } ] }, @@ -3836,7 +3887,7 @@ } }, "number-format": { - "doc": "Converts the input number into a string representation using the providing formatting rules. If set, the `locale` argument specifies the locale to use, as a BCP 47 language tag. If set, the `currency` argument specifies an ISO 4217 code to use for currency-style formatting. If set, the `min-fraction-digits` and `max-fraction-digits` arguments specify the minimum and maximum number of fractional digits to include.\n\n - [Display HTML clusters with custom properties](https://maplibre.org/maplibre-gl-js/docs/examples/display-html-clusters-with-custom-properties/)", + "doc": "Converts the input number into a string representation using the provided format_options.\n\n - [Display HTML clusters with custom properties](https://maplibre.org/maplibre-gl-js/docs/examples/display-html-clusters-with-custom-properties/)", "syntax": { "overloads": [ { @@ -3847,11 +3898,34 @@ "parameters": [ { "name": "input", - "type": "number" + "type": "number", + "doc": "number to format" }, { "name": "format_options", - "type": "{ \"locale\"?: string, \"currency\"?: string, \"min-fraction-digits\"?: number, \"max-fraction-digits\"?: number }" + "type": { + "locale": { + "type": "string", + "example": "en", + "doc": "Specifies the locale to use, as a BCP 47 language tag" + }, + "currency": { + "type": "string", + "example": "USD", + "doc": "An ISO 4217 code to use for currency-style formatting" + }, + "min-fraction-digits": { + "type": "number", + "example": 1, + "doc": "Minimum number of fractional digits to include" + }, + "max-fraction-digits": { + "type": "number", + "example": 2, + "doc": "Maximum number of fractional digits to include" + } + }, + "doc": "Format options for the number" } ] }, @@ -4143,7 +4217,7 @@ "parameters": [ { "name": "array_or_string", - "type": "array | string" + "type": ["array", "string"] } ] },