diff --git a/packages/docs/src/.q-press/api/components/MarkdownPage.json b/packages/docs/src/.q-press/api/components/MarkdownPage.json index fce4160a8..10372b051 100644 --- a/packages/docs/src/.q-press/api/components/MarkdownPage.json +++ b/packages/docs/src/.q-press/api/components/MarkdownPage.json @@ -6,7 +6,7 @@ "props": { "overline": { "type": "String", - "desc": "Text to display as an overline above the title", + "desc": "Text to display as an `overline` above the title", "examples": [ "'Introduction'", "'Chapter 1'" @@ -41,7 +41,7 @@ }, "isFullscreen": { "type": "Boolean", - "desc": "Flag to indicate if the page is in fullscreen mode", + "desc": "Flag to indicate if the page is in `fullscreen` mode", "category": "state" } }, diff --git a/packages/docs/src/.q-press/components/MarkdownApi.vue b/packages/docs/src/.q-press/components/MarkdownApi.vue index b0df8d379..f773010af 100644 --- a/packages/docs/src/.q-press/components/MarkdownApi.vue +++ b/packages/docs/src/.q-press/components/MarkdownApi.vue @@ -131,6 +131,12 @@ import MarkdownApiEntry from './MarkdownApiEntry' const defaultInnerTabName = '__default' +/** + * Extracts and categorizes properties based on their categories. + * + * @param {Object} props - The properties object where each key is a property name and each value is an object containing a `category` string. + * @returns {Array} - An array of unique category names sorted alphabetically. If there is only one unique category, returns an array with a default inner tab name. + */ function getPropsCategories(props) { const acc = new Set() @@ -147,6 +153,14 @@ function getPropsCategories(props) { return acc.size === 1 ? [defaultInnerTabName] : Array.from(acc).sort() } +/** + * Retrieves the inner tabs for a given API. + * + * @param {Object} api - The API object containing the data. + * @param {Array} tabs - The array of tabs to be populated. + * @param {string} apiType - The type of the API. + * @returns {Array} - The array of inner tabs. + */ function getInnerTabs(api, tabs, apiType) { const acc = {} @@ -160,6 +174,13 @@ function getInnerTabs(api, tabs, apiType) { return acc } +/** + * Parses the given API data and organizes it into tabs and inner tabs. + * + * @param {Object} api - The API data to be parsed. + * @param {Array} tabs - The array to store the main tabs. + * @param {Array} innerTabs - The array to store the inner tabs. + */ function parseApi(api, tabs, innerTabs) { const acc = {} @@ -193,6 +214,14 @@ function parseApi(api, tabs, innerTabs) { return acc } +/** + * Checks if a given item passes the specified filter criteria. + * + * @param {string} filter - The filter criteria to apply. + * @param {string} name - The name of the item to check. + * @param {string} desc - The description of the item to check. + * @returns {boolean} - Returns true if the item passes the filter, otherwise false. + */ function passesFilter(filter, name, desc) { return ( name.toLowerCase().indexOf(filter) > -1 || @@ -200,6 +229,15 @@ function passesFilter(filter, name, desc) { ) } +/** + * Filters the parsed API data based on the provided filter, tabs, and innerTabs. + * + * @param {Object} parsedApi - The parsed API data to be filtered. + * @param {string} filter - The filter criteria to apply to the parsed API data. + * @param {Array} tabs - The list of tabs to consider while filtering. + * @param {Array} innerTabs - The list of inner tabs to consider while filtering. + * @returns {Object} - The filtered API data. + */ function getFilteredApi(parsedApi, filter, tabs, innerTabs) { if (filter === '') { return parsedApi @@ -263,6 +301,14 @@ function getFilteredApi(parsedApi, filter, tabs, innerTabs) { return acc } +/** + * Calculates the count of API entries based on the provided parsed API data and tab configurations. + * + * @param {Object} parsedApi - The parsed API data. + * @param {Array} tabs - The array of main tab configurations. + * @param {Array} innerTabs - The array of inner tab configurations. + * @returns {number} - The count of API entries. + */ function getApiCount(parsedApi, tabs, innerTabs) { const acc = {} @@ -354,13 +400,37 @@ watch(currentTab, (val) => { }) const inputIcon = computed(() => (filter.value !== '' ? mdiClose : mdiMagnify)) + +/** + * A computed property that filters the API data based on certain criteria. + * The filtering logic is defined within the computed function. + * + * @returns {Array} The filtered API data. + */ const filteredApi = computed(() => getFilteredApi(apiDef.value, filter.value.toLowerCase(), tabsList.value, innerTabsList.value), ) + +/** + * A computed property that returns the count of filtered API items. + * This property is reactive and will update whenever the dependencies change. + */ const filteredApiCount = computed(() => getApiCount(filteredApi.value, tabsList.value, innerTabsList.value), ) +/** + * Parses the API file and extracts relevant information. + * + * @param {string} name - The name of the API file. + * @param {Object} options - The options object containing various properties. + * @param {string} options.type - The type of the API. + * @param {string} options.behavior - The behavior of the API. + * @param {Object} options.meta - Metadata associated with the API. + * @param {string} options.addedIn - The version in which the API was added. + * @param {Object} api - Additional API properties. + * @returns {Object} The parsed API information. + */ function parseApiFile(name, { type, behavior, meta, addedIn, ...api }) { nameBanner.value = `${name} API` apiPath.value = meta.docsUrl diff --git a/packages/docs/src/.q-press/components/MarkdownApiEntry.ts b/packages/docs/src/.q-press/components/MarkdownApiEntry.ts index 91380a2dd..b828c8a80 100644 --- a/packages/docs/src/.q-press/components/MarkdownApiEntry.ts +++ b/packages/docs/src/.q-press/components/MarkdownApiEntry.ts @@ -3,6 +3,13 @@ import { QBadge, QBtn, Notify, QBtnToggle } from 'quasar' import { copyToClipboard } from './markdown-utils' import { mdiMinusBox, mdiPlusBox } from '@quasar/extras/mdi-v7' +/** + * This function copies a given property name to the clipboard. + * It also displays a notification to the user confirming the successful copy. + * + * @param propName - The name of the property to be copied. + * @returns {void} - This function does not return any value. + */ function copyPropName(propName: string): void { copyToClipboard(propName) @@ -14,6 +21,16 @@ function copyPropName(propName: string): void { }) } +/** + * Generates a string representation of event parameters for a given event object. + * + * @param event - An object containing event information. + * @param event.params - An optional record of parameter names and their corresponding types. + * If undefined, null, or empty, an empty string is used for parameters. + * + * @returns A string representation of the event parameters in the format "(param1, param2, ...) => void". + * If no parameters are present, it returns "() => void". + */ function getEventParams(event: { params?: Record | null }): string { const params = event.params === void 0 || event.params === null || event.params.length === 0 @@ -23,6 +40,21 @@ function getEventParams(event: { params?: Record | null }): string return `(${params}) => void` } +/** + * Generates a string representation of method parameters. + * + * This function takes a method object and an optional flag to determine how to format the parameters. + * It handles cases where there are no parameters, all parameters are required, or there's a mix of required and optional parameters. + * + * @param method - An object containing information about the method. + * @param method.params - A record of parameter names and their corresponding details. Can be undefined, null, or empty. + * @param noRequired - A boolean flag. If true, all parameters are treated as required. If false or undefined, the function distinguishes between required and optional parameters. + * + * @returns A string representation of the method parameters enclosed in parentheses. + * - Returns " ()" if there are no parameters. + * - If noRequired is true, returns all parameters joined by commas. + * - If noRequired is false or undefined, optional parameters are suffixed with "?". + */ function getMethodParams( method: { params?: Record | null }, noRequired?: boolean, @@ -51,6 +83,18 @@ function getMethodParams( return ' (' + str + ')' } +/** + * Generates a string representation of a method's return value. + * + * @param method - An object containing information about the method. + * @param method.returns - An optional object containing the return type information. + * If undefined or null, the method is considered to return void. + * @param method.returns.type - The type of the return value. + * + * @returns A string representation of the method's return value, + * prefixed with " => ". If no return value is specified, + * it returns " => void". + */ function getMethodReturnValue(method: { returns?: { type: any } | null }): string { return ( ' => ' + @@ -60,6 +104,12 @@ function getMethodReturnValue(method: { returns?: { type: any } | null }): strin ) } +/** + * Converts a type value to its string representation. + * + * @param type - The type value to convert. Can be an array of types or a single type. + * @returns A string representation of the type. If the input is an array, it joins the types with ' | '. + */ function getStringType(type: any): string { return Array.isArray(type) ? type.join(' | ') : type } @@ -67,13 +117,35 @@ function getStringType(type: any): string { const NAME_PROP_COLOR = ['orange-8', 'brand-primary', 'green-5', 'purple-5'] const NAME_PROP_COLOR_LEN = NAME_PROP_COLOR.length +/** + * Creates a div element with specific classes and content for use in a markdown API entry. + * + * @param col - The number of columns the div should span on small screens and above. + * @param propName - The name of the property to be displayed in the div. + * @param propValue - Optional. The value of the property to be displayed. If undefined, the slot will be used instead. + * @param slot - Optional. A slot to be used for custom content when propValue is undefined. + * @returns A VNode representing the created div element. + */ function getDiv(col: number, propName: string, propValue?: string, slot?: any): VNode { return h('div', { class: `markdown-api-entry__item col-xs-12 col-sm-${col}` }, [ h('div', { class: 'markdown-api-entry__type' }, propName), - propValue !== void 0 ? h('div', { class: 'markdown-api-entry__value' }, propValue) : slot, + propValue !== void 0 + ? h('div', { class: 'markdown-api-entry__value' }, parseForInlineCode(propValue)) + : slot, ]) } +/** + * Creates a div element representing a name entry in the markdown API documentation. + * This function generates a complex div structure with badges and labels for API properties. + * + * @param prop - An object containing property information. It may include 'required' and 'addedIn' fields. + * @param label - The main text label for the property. + * @param level - A number indicating the nesting level of the property, used for color selection. + * @param suffix - Optional. Additional text to be appended after the main label. + * @param prefix - Optional. Text to be prepended before the main label. + * @returns A VNode representing the constructed div element for the name entry. + */ function getNameDiv( prop: any, label: string, @@ -116,6 +188,20 @@ function getNameDiv( return h('div', { class: 'markdown-api-entry__item col-xs-12 col-sm-12 row items-center' }, child) } +/** + * Creates an expandable section for API documentation. + * + * This function generates a VNode array representing an expandable section + * in the API documentation. It includes a description and, if expandable, + * a toggle button to show/hide additional details. + * + * @param openState - A reactive reference to an object tracking the open state of expandable sections. + * @param desc - The description text to be displayed. + * @param isExpandable - A boolean indicating whether the section should be expandable. + * @param key - A unique key for this expandable section, used to track its open state. + * @param getDetails - A function that returns an array of additional details to be shown when expanded. + * @returns An array of VNodes representing the expandable section. + */ function getExpandable( openState: Ref>, desc: string, @@ -140,7 +226,7 @@ function getExpandable( }, }), ]), - h('div', { class: 'markdown-api-entry__value' }, desc), + h('div', { class: 'markdown-api-entry__value' }, parseForInlineCode(desc)), ]), ] @@ -150,6 +236,39 @@ function getExpandable( } } +/** + * Parses a string for inline code segments and converts them into VNodes with special styling. + * + * This function splits the input string by backticks and creates VNodes for code segments. + * Text outside of backticks is left as plain strings. + * + * @param code - The input string containing potential inline code segments delimited by backticks. + * @returns An array of VNodes and strings, where code segments are wrapped in styled span elements. + */ +function parseForInlineCode(code: string) { + const parts = code.split(/(`[^`]+`)/g) + return parts.map((part) => { + if (part.startsWith('`') && part.endsWith('`')) { + return h('span', { class: 'markdown-token' }, part.slice(1, -1)) + } else { + return part + } + }) +} + +/** + * Generates detailed property information for API documentation. + * + * This function creates a series of VNodes that represent various aspects of a property, + * including its synchronization status, default value, external links, accepted values, + * nested properties, parameters, return types, scope, and examples. + * + * @param openState - A reactive reference to an object tracking the open state of expandable sections. + * @param masterKey - A unique identifier for the property, used in generating child keys. + * @param prop - The property object containing all the details to be displayed. + * @param level - The nesting level of the property, used for styling and indentation. + * @returns An array of VNodes representing the detailed property information. + */ function getPropDetails( openState: Ref>, masterKey: string, @@ -261,6 +380,21 @@ function getPropDetails( return details } +/** + * Generates VNodes for a property in the API documentation. + * + * This function creates a detailed representation of a property, including its name, + * type, description, and any additional details. It handles configuration toggles, + * expandable sections, and nested properties. + * + * @param openState - A reactive reference to an object tracking the open state of expandable sections. + * @param masterKey - A unique identifier for the property, used in generating child keys. + * @param prop - The property object containing all the details to be displayed. + * @param propName - The name of the property. If undefined, the property is treated as a nested or unnamed property. + * @param level - The nesting level of the property, used for styling and indentation. + * @param onlyChildren - If true, only child elements are returned without wrapping them in a container. + * @returns An array of VNodes representing the property and its details. + */ function getProp( openState: Ref>, masterKey: string, @@ -331,6 +465,18 @@ describe.props = describePropsLike('props') describe.computedProps = describePropsLike('computedProps') describe.slots = describePropsLike('slots') +/** + * Generates VNodes for event descriptions in the API documentation. + * + * This function creates a detailed representation of events, including their names, + * parameters, and descriptions. It handles expandable sections for each event + * and generates child elements for event parameters. + * + * @param openState - A reactive reference to an object tracking the open state of expandable sections. + * @param events - An object containing event definitions. Each key is an event name, + * and the value is an object describing the event. + * @returns An array of VNodes representing the events and their details. + */ describe.events = (openState: Ref>, events: any): VNode[] => { const child: VNode[] = [] @@ -375,6 +521,18 @@ describe.events = (openState: Ref>, events: any): VNode[ return child } +/** + * Generates VNodes for method descriptions in the API documentation. + * + * This function creates a detailed representation of methods, including their names, + * parameters, return types, and descriptions. It handles expandable sections for each method + * and generates child elements for method parameters and return values. + * + * @param openState - A reactive reference to an object tracking the open state of expandable sections. + * @param methods - An object containing method definitions. Each key is a method name, + * and the value is an object describing the method. + * @returns An array of VNodes representing the methods and their details. + */ describe.methods = (openState: Ref>, methods: any) => { const child: VNode[] = [] @@ -440,6 +598,20 @@ describe.methods = (openState: Ref>, methods: any) => { return child } +/** + * Generates VNodes for describing a value in the API documentation. + * + * This function creates a detailed representation of a value, including its type + * and any additional properties. It uses the 'getDiv' and 'getProp' helper functions + * to generate the necessary VNodes. + * + * @param openState - A reactive reference to an object tracking the open state of expandable sections. + * This is used to manage the state of collapsible content. + * @param value - An object containing the details of the value to be described. + * It should include at least a 'type' property. + * @returns An array of VNodes representing the value description, wrapped in a div + * with the class 'markdown-api-entry row'. + */ describe.value = (openState: Ref>, value: any): VNode[] => { return [ h( @@ -452,6 +624,20 @@ describe.value = (openState: Ref>, value: any): VNode[] ] } +/** + * Generates VNodes for describing an argument in the API documentation. + * + * This function creates a detailed representation of an argument, including its type + * and any additional properties. It uses the 'getDiv' and 'getProp' helper functions + * to generate the necessary VNodes. + * + * @param openState - A reactive reference to an object tracking the open state of expandable sections. + * This is used to manage the state of collapsible content. + * @param arg - An object containing the details of the argument to be described. + * It should include at least a 'type' property. + * @returns An array containing a single VNode representing the argument description, + * wrapped in a div with the class 'markdown-api-entry row'. + */ describe.arg = (openState: Ref>, arg: any): VNode[] => { return [ h( @@ -464,6 +650,20 @@ describe.arg = (openState: Ref>, arg: any): VNode[] => { ] } +/** + * Generates VNodes for describing modifiers in the API documentation. + * + * This function creates a detailed representation of modifiers, including their names + * and properties. It iterates through the provided modifiers and generates + * a VNode for each one using the 'getProp' helper function. + * + * @param openState - A reactive reference to an object tracking the open state of expandable sections. + * This is used to manage the state of collapsible content. + * @param modifiers - An object containing modifier definitions. Each key is a modifier name, + * and the value is an object describing the modifier. + * @returns An array of VNodes representing the modifiers and their details, + * each wrapped in a div with the class 'markdown-api-entry row'. + */ describe.modifiers = (openState: Ref>, modifiers: any): VNode[] => { const child: VNode[] = [] @@ -482,10 +682,37 @@ describe.modifiers = (openState: Ref>, modifiers: any): return child } +/** + * Generates a VNode array for describing an injection in the API documentation. + * + * This function creates a single div element containing the injection's name and details. + * + * @param _ - A Ref object containing a record of boolean values. This parameter is not used in the function. + * @param injection - An object containing the details of the injection to be described. + * @returns An array containing a single VNode representing the injection description, + * wrapped in a div with the class 'markdown-api-entry row'. + */ describe.injection = (_: Ref>, injection: any): VNode[] => { return [h('div', { class: 'markdown-api-entry row' }, [getNameDiv(injection, injection, 0)])] } +/** + * Creates a configuration toggle object for managing UI and config file options. + * + * This function generates an object with properties and methods to handle + * the state of configuration options, allowing toggling between UI config + * and config file modes. + * + * @param openState - A reactive reference to an object containing boolean values + * representing the open state of various UI elements. + * The `quasarConfOptions` property is used to determine + * the current configuration mode. + * + * @returns An object with the following properties: + * - enabled: A boolean indicating whether configuration options are available. + * - type: A string representing the current configuration mode ('uiConfig' or 'configFile'). + * - setType: A function to update the configuration mode. + */ function useConfigToggle(openState: Ref>) { return { enabled: openState.value.quasarConfOptions !== undefined, @@ -496,6 +723,21 @@ function useConfigToggle(openState: Ref>) { } } +/** + * Generates VNodes for describing Quasar configuration options in the API documentation. + * + * This function creates a detailed representation of Quasar configuration options, + * including their names, types, and descriptions. It handles both UI config and + * config file modes, and generates appropriate UI elements for each. + * + * @param openState - A reactive reference to an object tracking the open state of expandable sections. + * It also contains information about the current configuration mode. + * @param conf - An object containing the configuration options to be described. + * It should include properties like 'propName', 'type', 'desc', and 'definition'. + * + * @returns An array containing a single VNode representing the configuration options description, + * wrapped in a div with the class 'markdown-api-entry row'. + */ describe.quasarConfOptions = (openState: Ref>, conf: any): VNode[] => { const configToggle = useConfigToggle(openState) diff --git a/packages/docs/src/.q-press/components/MarkdownExample.vue b/packages/docs/src/.q-press/components/MarkdownExample.vue index 6df253df8..ade5d2c0e 100644 --- a/packages/docs/src/.q-press/components/MarkdownExample.vue +++ b/packages/docs/src/.q-press/components/MarkdownExample.vue @@ -6,18 +6,11 @@
- - + { return props.scrollable === true ? 'markdown-example__content--scrollable scroll-y' @@ -142,6 +141,13 @@ const componentClass = computed(() => { : '' }) +/** + * Parses a given template and applies it to the target. + * + * @param {Object} target - The target object to which the template will be applied. + * @param {string} template - The template string to be parsed and applied. + * @returns {void} + */ function parseTemplate(target, template) { const string = `(<${target}(.*)?>[\\w\\W]*<\\/${target}>)`, regex = new RegExp(string, 'g'), @@ -150,6 +156,12 @@ function parseTemplate(target, template) { return parsed[1] || '' } +/** + * Parses a given component. + * + * @param {Object} comp - The component to be parsed. + * @returns {Object} The parsed component. + */ function parseComponent(comp) { def.parts = { Template: parseTemplate('template', comp),