docs: update jsdocs enabling possibility to generate typescript defs (#750)

This commit is contained in:
Thomas Bengtsson
2022-02-04 08:36:24 +01:00
committed by GitHub
parent 09f4627bd1
commit ea50d8cf56
11 changed files with 231 additions and 121 deletions

View File

@@ -13,10 +13,10 @@
/**
* @since 1.1.0
* @interface ExportDataDef
* @property {qae.NxDimension[]} dimensions
* @property {qae.NxMeasure[]} measures
* @property {qae.NxDimension[]} excludedDimensions
* @property {qae.NxMeasure[]} excludedMeasures
* @property {EngineAPI.INxDimension[]} dimensions
* @property {EngineAPI.INxMeasure[]} measures
* @property {EngineAPI.INxDimension[]} excludedDimensions
* @property {EngineAPI.INxMeasure[]} excludedMeasures
* @property {number[]} interColumnSortOrder
*/

View File

@@ -12,20 +12,20 @@ module.exports = {
},
parse: {
types: {
'enigma.Doc': {
url: 'https://github.com/qlik-oss/enigma.js/blob/master/docs/api.md#generated-api',
'EngineAPI.IApp': {
url: 'https://qlik.dev/apis/json-rpc/qix/doc#%23%2Fentries%2FDoc',
},
'qae.GenericObjectLayout': {
url: 'https://core.qlik.com/services/qix-engine/apis/qix/definitions/#genericobjectlayout',
'EngineAPI.IGenericObjectLayout': {
url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FGenericObjectLayout',
},
'qae.GenericObjectProperties': {
url: 'https://core.qlik.com/services/qix-engine/apis/qix/definitions/#genericobjectproperties',
'EngineAPI.IGenericObjectProperties': {
url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FGenericObjectProperties',
},
'qae.NxDimension': {
url: 'https://core.qlik.com/services/qix-engine/apis/qix/definitions/#nxdimension',
'EngineAPI.INxDimension': {
url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FNxDimension',
},
'qae.NxMeasure': {
url: 'https://core.qlik.com/services/qix-engine/apis/qix/definitions/#nxmeasure',
'EngineAPI.INxMeasure': {
url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FNxMeasure',
},
},
},

View File

@@ -3,10 +3,16 @@ import InstanceContext from '../contexts/InstanceContext';
import useRect from '../hooks/useRect';
import RenderDebouncer from '../utils/render-debouncer';
/**
* @interface VizElementAttributes
* @extends NamedNodeMap
* @property {string} data-render-count
*/
/**
* @interface
* @extends HTMLElement
* @property {string} attributes.data-render-count
* @property {VizElementAttributes} attributes
*/
const VizElement = {
/** @type {'njs-viz'} */

View File

@@ -117,7 +117,7 @@ function nuked(configuration = {}) {
* Initiates a new `Embed` instance using the specified enigma `app`.
* @entry
* @function embed
* @param {enigma.Doc} app
* @param {EngineAPI.IApp} app
* @param {Configuration=} instanceConfig
* @returns {Embed}
* @example
@@ -446,6 +446,10 @@ function nuked(configuration = {}) {
return embed;
}
/**
* @typedef {any} ThemeJSON
*/
/**
* @interface ThemeInfo
* @property {string} id Theme identifier

View File

@@ -3,7 +3,7 @@ import init from './initiate';
import { subscribe, modelStore } from '../stores/model-store';
/**
* @typedef {string | qae.NxDimension | qae.NxMeasure | LibraryField} Field
* @typedef {string | EngineAPI.INxDimension | EngineAPI.INxMeasure | LibraryField} Field
*/
/**
@@ -13,7 +13,7 @@ import { subscribe, modelStore } from '../stores/model-store';
* @property {string} type
* @property {string} version
* @property {(Field[])=} fields
* @property {qae.GenericObjectProperties=} properties
* @property {EngineAPI.IGenericObjectProperties=} properties
*/
export default async function createSessionObject(
{ type, version, fields, properties, options, plugins, element },

View File

@@ -21,23 +21,23 @@ module.exports = {
parse: {
types: {
undefined: {},
'qae.NxAppLayout': {},
'enigma.GenericObject': {},
'enigma.Global': {},
'enigma.Doc': {
url: 'https://github.com/qlik-oss/enigma.js/blob/master/docs/api.md#generated-api',
'EngineAPI.INxAppLayout': {},
'EngineAPI.IGenericObject': {},
'EngineAPI.IGlobal': {},
'EngineAPI.IApp': {
url: 'https://qlik.dev/apis/json-rpc/qix/doc#%23%2Fentries%2FDoc',
},
'qae.GenericObjectLayout': {
url: 'https://core.qlik.com/services/qix-engine/apis/qix/definitions/#genericobjectlayout',
'EngineAPI.IGenericObjectLayout': {
url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FGenericObjectLayout',
},
'qae.GenericObjectProperties': {
url: 'https://core.qlik.com/services/qix-engine/apis/qix/definitions/#genericobjectproperties',
'EngineAPI.IGenericObjectProperties': {
url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FGenericObjectProperties',
},
'qae.NxDimension': {
url: 'https://core.qlik.com/services/qix-engine/apis/qix/definitions/#nxdimension',
'EngineAPI.INxDimension': {
url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FNxDimension',
},
'qae.NxMeasure': {
url: 'https://core.qlik.com/services/qix-engine/apis/qix/definitions/#nxmeasure',
'EngineAPI.INxMeasure': {
url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FNxMeasure',
},
},
},

View File

@@ -14,7 +14,7 @@
"params": [
{
"name": "app",
"type": "enigma.Doc"
"type": "EngineAPI.IApp"
},
{
"name": "instanceConfig",
@@ -229,7 +229,7 @@
"kind": "function",
"params": [],
"returns": {
"type": "qae.GenericObjectLayout"
"type": "EngineAPI.IGenericObjectLayout"
},
"examples": [
"import { useLayout } from '@nebula.js/stardust';\n// ...\nconst layout = useLayout();\nconsole.log(layout);"
@@ -240,7 +240,7 @@
"kind": "function",
"params": [],
"returns": {
"type": "qae.GenericObjectLayout"
"type": "EngineAPI.IGenericObjectLayout"
},
"examples": [
"import { useStaleLayout } from '@nebula.js/stardust';\n// ...\nconst staleLayout = useStaleLayout();\nconsole.log(staleLayout);"
@@ -252,7 +252,7 @@
"params": [],
"returns": {
"description": "The app layout",
"type": "qae.NxAppLayout"
"type": "EngineAPI.INxAppLayout"
},
"examples": [
"import { useAppLayout } from '@nebula.js/stardust';\n// ...\nconst appLayout = useAppLayout();\nconsole.log(appLayout.qLocaleInfo);"
@@ -266,7 +266,7 @@
"kind": "union",
"items": [
{
"type": "enigma.GenericObject"
"type": "EngineAPI.IGenericObject"
},
{
"type": "undefined"
@@ -286,7 +286,7 @@
"kind": "union",
"items": [
{
"type": "enigma.Doc"
"type": "EngineAPI.IApp"
},
{
"type": "undefined"
@@ -306,7 +306,7 @@
"kind": "union",
"items": [
{
"type": "enigma.Global"
"type": "EngineAPI.IGlobal"
},
{
"type": "undefined"
@@ -466,14 +466,14 @@
"kind": "function",
"params": [
{
"type": "qae.GenericObjectLayout"
"type": "EngineAPI.IGenericObjectLayout"
}
],
"returns": {
"type": "Promise",
"generics": [
{
"type": "qae.GenericObjectLayout"
"type": "EngineAPI.IGenericObjectLayout"
}
]
}
@@ -490,15 +490,7 @@
"params": [],
"returns": {
"description": "The render state.",
"kind": "object",
"entries": {
"pending": {
"type": "any"
},
"restore": {
"type": "any"
}
}
"type": "#/definitions/RenderState"
},
"examples": [
"import { useRenderState } from '@nebula.js/stardust';\n\nconst renderState = useRenderState();\nuseState(() => {\n if(needProperteisUpdate(...)) {\n useRenderState.pending();\n updateProperties(...);\n } else {\n useRenderState.restore();\n ...\n }\n}, [...]);"
@@ -730,6 +722,19 @@
}
}
},
"ReceiverFunction": {
"description": "A callback function which receives another function as input.",
"kind": "alias",
"items": {
"kind": "function",
"params": [
{
"kind": "function",
"params": []
}
]
}
},
"FieldInstance": {
"availability": {
"since": "1.1.0"
@@ -798,6 +803,21 @@
"optional": true,
"defaultValue": "{}",
"type": "object"
},
"sessionModel": {
"description": "Use a custom sessionModel.",
"optional": true,
"type": "object"
},
"selectionsApi": {
"description": "Use a custom selectionsApi to customize how values are selected.",
"optional": true,
"type": "object"
},
"update": {
"description": "A function which receives an update function which upon call will trigger a data fetch.",
"optional": true,
"type": "#/definitions/ReceiverFunction"
}
}
}
@@ -815,6 +835,12 @@
}
}
},
"ThemeJSON": {
"kind": "alias",
"items": {
"type": "any"
}
},
"ThemeInfo": {
"kind": "interface",
"entries": {
@@ -830,7 +856,7 @@
"type": "Promise",
"generics": [
{
"type": "ThemeJSON"
"type": "#/definitions/ThemeJSON"
}
]
}
@@ -1112,10 +1138,10 @@
"type": "string"
},
{
"type": "qae.NxDimension"
"type": "EngineAPI.INxDimension"
},
{
"type": "qae.NxMeasure"
"type": "EngineAPI.INxMeasure"
},
{
"type": "#/definitions/LibraryField"
@@ -1152,7 +1178,7 @@
},
"properties": {
"optional": true,
"type": "qae.GenericObjectProperties"
"type": "EngineAPI.IGenericObjectProperties"
}
}
},
@@ -1381,6 +1407,19 @@
}
}
},
"VizElementAttributes": {
"extends": [
{
"type": "NamedNodeMap"
}
],
"kind": "interface",
"entries": {
"data-render-count": {
"type": "string"
}
}
},
"VizElement": {
"extends": [
{
@@ -1390,12 +1429,7 @@
"kind": "interface",
"entries": {
"attributes": {
"kind": "object",
"entries": {
"data-render-count": {
"type": "string"
}
}
"type": "#/definitions/VizElementAttributes"
},
"className": {
"value": "'njs-viz'",
@@ -1573,6 +1607,17 @@
}
}
},
"RenderState": {
"kind": "interface",
"entries": {
"pending": {
"type": "any"
},
"restore": {
"type": "any"
}
}
},
"Keyboard": {
"stability": "experimental",
"kind": "interface",
@@ -1677,7 +1722,7 @@
"entries": {
"properties": {
"optional": true,
"type": "qae.GenericObjectProperties"
"type": "EngineAPI.IGenericObjectProperties"
},
"data": {
"optional": true,
@@ -1712,7 +1757,7 @@
"type": "#/definitions/FieldTarget",
"generics": [
{
"type": "qae.NxDimension"
"type": "EngineAPI.INxDimension"
}
]
},
@@ -1721,12 +1766,55 @@
"type": "#/definitions/FieldTarget",
"generics": [
{
"type": "qae.NxMeasure"
"type": "EngineAPI.INxMeasure"
}
]
}
}
},
"fieldTargetAddedCallback": {
"templates": [
{
"name": "T"
}
],
"kind": "function",
"params": [
{
"name": "field",
"description": "TODO validate param name",
"type": "T"
},
{
"name": "properties",
"type": "EngineAPI.IGenericObjectProperties"
}
]
},
"fieldTargetRemovedCallback": {
"templates": [
{
"name": "T"
}
],
"kind": "function",
"params": [
{
"name": "field",
"description": "TODO validate param name",
"type": "T"
},
{
"name": "properties",
"type": "EngineAPI.IGenericObjectProperties"
},
{
"name": "index",
"description": "TODO validate param name",
"type": "number"
}
]
},
"FieldTarget": {
"templates": [
{
@@ -1753,28 +1841,19 @@
},
"added": {
"optional": true,
"kind": "function",
"params": [
"type": "#/definitions/fieldTargetAddedCallback",
"generics": [
{
"type": "T"
},
{
"type": "qae.GenericObjectProperties"
}
]
},
"removed": {
"optional": true,
"kind": "function",
"params": [
"type": "#/definitions/fieldTargetRemovedCallback",
"generics": [
{
"type": "T"
},
{
"type": "qae.GenericObjectProperties"
},
{
"type": "number"
}
]
}
@@ -2101,25 +2180,25 @@
"dimensions": {
"kind": "array",
"items": {
"type": "qae.NxDimension"
"type": "EngineAPI.INxDimension"
}
},
"measures": {
"kind": "array",
"items": {
"type": "qae.NxMeasure"
"type": "EngineAPI.INxMeasure"
}
},
"excludedDimensions": {
"kind": "array",
"items": {
"type": "qae.NxDimension"
"type": "EngineAPI.INxDimension"
}
},
"excludedMeasures": {
"kind": "array",
"items": {
"type": "qae.NxMeasure"
"type": "EngineAPI.INxMeasure"
}
},
"interColumnSortOrder": {

View File

@@ -18,14 +18,14 @@ module.exports = {
},
parse: {
types: {
'qae.GenericObjectProperties': {},
'qae.GenericObjectLayout': {},
'qae.NxAppLayout': {},
'qae.NxDimension': {},
'qae.NxMeasure': {},
'enigma.GenericObject': {},
'enigma.Doc': {},
'enigma.Global': {},
'EngineAPI.IGenericObjectProperties': {},
'EngineAPI.IGenericObjectLayout': {},
'EngineAPI.INxAppLayout': {},
'EngineAPI.INxDimension': {},
'EngineAPI.INxMeasure': {},
'EngineAPI.IGenericObject': {},
'EngineAPI.IDoc': {},
'EngineAPI.IGlobal': {},
},
},
},

View File

@@ -550,7 +550,7 @@ export function useRect() {
/**
* Gets the layout of the generic object associated with this visualization.
* @entry
* @returns {qae.GenericObjectLayout}
* @returns {EngineAPI.IGenericObjectLayout}
* @example
* import { useLayout } from '@nebula.js/stardust';
* // ...
@@ -570,7 +570,7 @@ export function useLayout() {
* The returned value from `useStaleLayout()` and `useLayout()` are identical when the object
* is not in a modal state.
* @entry
* @returns {qae.GenericObjectLayout}
* @returns {EngineAPI.IGenericObjectLayout}
* @example
* import { useStaleLayout } from '@nebula.js/stardust';
* // ...
@@ -589,7 +589,7 @@ export function useStaleLayout() {
/**
* Gets the layout of the app associated with this visualization.
* @entry
* @returns {qae.NxAppLayout} The app layout
* @returns {EngineAPI.INxAppLayout} The app layout
* @example
* import { useAppLayout } from '@nebula.js/stardust';
* // ...
@@ -603,7 +603,7 @@ export function useAppLayout() {
/**
* Gets the generic object API of the generic object connected to this visualization.
* @entry
* @returns {enigma.GenericObject|undefined}
* @returns {EngineAPI.IGenericObject|undefined}
* @example
* import { useModel } from '@nebula.js/stardust';
* // ...
@@ -622,7 +622,7 @@ export function useModel() {
/**
* Gets the doc API.
* @entry
* @returns {enigma.Doc|undefined} The doc API.
* @returns {EngineAPI.IApp|undefined} The doc API.
* @example
* import { useApp } from '@nebula.js/stardust';
* // ...
@@ -641,7 +641,7 @@ export function useApp() {
/**
* Gets the global API.
* @entry
* @returns {enigma.Global|undefined} The global API.
* @returns {EngineAPI.IGlobal|undefined} The global API.
* @example
* import { useGlobal } from '@nebula.js/stardust';
*
@@ -965,7 +965,7 @@ export function useImperativeHandle(fn, deps) {
/**
* Registers a callback that is called when a snapshot is taken.
* @entry
* @param {function(qae.GenericObjectLayout): Promise<qae.GenericObjectLayout>} snapshotCallback
* @param {function(EngineAPI.IGenericObjectLayout): Promise<EngineAPI.IGenericObjectLayout>} snapshotCallback
* @example
* import { onTakeSnapshot } from '@nebula.js/stardust';
* import { useState } from '@nebula.js/stardust';
@@ -988,13 +988,19 @@ export function onTakeSnapshot(cb) {
h.fn = cb;
}
/**
* @interface RenderState
* @property {any} pending
* @property {any} restore
*/
/**
* Gets render state instance.
*
* Used to update properties and get a new layout without triggering onInitialRender.
* @entry
* @experimental
* @returns {{ pending, restore }} The render state.
* @returns {RenderState} The render state.
* @example
* import { useRenderState } from '@nebula.js/stardust';
*

View File

@@ -25,7 +25,7 @@ const noop = () => {};
/**
* @interface QAEDefinition
* @property {qae.GenericObjectProperties=} properties
* @property {EngineAPI.IGenericObjectProperties=} properties
* @property {object=} data
* @property {DataTarget[]} data.targets
* @property {importProperties=} importProperties
@@ -35,8 +35,23 @@ const noop = () => {};
/**
* @interface DataTarget
* @property {string} path
* @property {FieldTarget<qae.NxDimension>=} dimensions
* @property {FieldTarget<qae.NxMeasure>=} measures
* @property {FieldTarget<EngineAPI.INxDimension>=} dimensions
* @property {FieldTarget<EngineAPI.INxMeasure>=} measures
*/
/**
* @callback fieldTargetAddedCallback
* @template T
* @param {T} field TODO validate param name
* @param {EngineAPI.IGenericObjectProperties} properties
*/
/**
* @callback fieldTargetRemovedCallback
* @template T
* @param {T} field TODO validate param name
* @param {EngineAPI.IGenericObjectProperties} properties
* @param {number} index TODO validate param name
*/
/**
@@ -44,8 +59,8 @@ const noop = () => {};
* @template T
* @property {function():number} [min]
* @property {function():number} [max]
* @property {function(T, qae.GenericObjectProperties)} [added]
* @property {function(T, qae.GenericObjectProperties, number)} [removed]
* @property {fieldTargetAddedCallback<T>} [added]
* @property {fieldTargetRemovedCallback<T>} [removed]
*/
function fallback(x, value) {

View File

@@ -46,7 +46,7 @@ title: API Reference
- [interface: CreateConfig](#interface-createconfig)
- [interface: BaseConfig](#interface-baseconfig)
- [interface: GetConfig](#interface-getconfig)
- [type Field = <[string]|`qae.NxDimension`|`qae.NxMeasure`|[LibraryField]>](#type-field-stringqaenxdimensionqaenxmeasurelibraryfield)
- [type Field = <[string]|`EngineAPI.INxDimension`|`EngineAPI.INxMeasure`|[LibraryField]>](#type-field-stringqaenxdimensionqaenxmeasurelibraryfield)
- [interface: LibraryField](#interface-libraryfield)
- [class: AppSelections](#class-appselections)
- [appSelections.mount(element)](#appselectionsmountelement)
@@ -97,7 +97,7 @@ title: API Reference
### function: embed(app[, instanceConfig])
- `app` <`enigma.Doc`>
- `app` <`EngineAPI.IApp`>
- `instanceConfig` <[Configuration]>
- `returns:` <[Embed]>
@@ -242,7 +242,7 @@ useEffect(() => {
### function: useLayout()
- `returns:` <`qae.GenericObjectLayout`>
- `returns:` <`EngineAPI.IGenericObjectLayout`>
Gets the layout of the generic object associated with this supernova.
@@ -255,7 +255,7 @@ console.log(layout);
### function: useStaleLayout()
- `returns:` <`qae.GenericObjectLayout`>
- `returns:` <`EngineAPI.IGenericObjectLayout`>
Gets the layout of the generic object associated with this supernova.
@@ -274,7 +274,7 @@ console.log(staleLayout);
### function: useAppLayout()
- `returns:` <`qae.NxAppLayout`> The app layout
- `returns:` <`EngineAPI.INxAppLayout`> The app layout
Gets the layout of the app associated with this supernova.
@@ -287,7 +287,7 @@ console.log(appLayout.qLocaleInfo);
### function: useModel()
- `returns:` <`enigma.GenericObject`|`undefined`>
- `returns:` <`EngineAPI.IGenericObject`|`undefined`>
Gets the generic object API of the generic object connected to this supernova.
@@ -304,7 +304,7 @@ useEffect(() => {
### function: useApp()
- `returns:` <`enigma.Doc`|`undefined`> The doc API.
- `returns:` <`EngineAPI.IApp`|`undefined`> The doc API.
Gets the doc API.
@@ -321,7 +321,7 @@ useEffect(() => {
### function: useGlobal()
- `returns:` <`enigma.Global`|`undefined`> The global API.
- `returns:` <`EngineAPI.IGlobal`|`undefined`> The global API.
Gets the global API.
@@ -617,7 +617,7 @@ const ctl = ctl.destroy();
* `type` <[string]>
* `version` <[string]>
* `fields` <[Array]>
* `properties` <`qae.GenericObjectProperties`>
* `properties` <`EngineAPI.IGenericObjectProperties`>
### interface: BaseConfig
@@ -630,7 +630,7 @@ const ctl = ctl.destroy();
* `id` <[string]>
### type Field = <[string]|`qae.NxDimension`|`qae.NxMeasure`|[LibraryField]>
### type Field = <[string]|`EngineAPI.INxDimension`|`EngineAPI.INxMeasure`|[LibraryField]>
### interface: LibraryField
@@ -792,15 +792,15 @@ export default function () {
### interface: QAEDefinition
- `properties` <`qae.GenericObjectProperties`>
- `properties` <`EngineAPI.IGenericObjectProperties`>
- `data` <[Object]>
- `targets` <[Array]<[DataTarget]>>
### interface: DataTarget
- `path` <[string]>
- `dimensions` <[FieldTarget]<`qae.NxDimension`>>
- `measures` <[FieldTarget]<`qae.NxMeasure`>>
- `dimensions` <[FieldTarget]<`EngineAPI.INxDimension`>>
- `measures` <[FieldTarget]<`EngineAPI.INxMeasure`>>
### interface: FieldTarget
@@ -923,26 +923,26 @@ theme.getStyle('', '', 'fontSize');
- `nil` <[string]>
- `others` <[string]>
[enigma.doc]: undefined
[engineapi.iapp]: undefined
[s]: undefined
[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
[array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
[any]: undefined
[t]: undefined
[htmlelement]: undefined
[qae.genericobjectlayout]: undefined
[qae.nxapplayout]: undefined
[enigma.genericobject]: undefined
[engineapi.igenericobjectlayout]: undefined
[engineapi.inxapplayout]: undefined
[engineapi.igenericobject]: undefined
[undefined]: undefined
[enigma.global]: undefined
[engineapi.iglobal]: undefined
[a]: undefined
[object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
[promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
[qae.genericobjectproperties]: undefined
[qae.nxdimension]: undefined
[qae.nxmeasure]: undefined
[engineapi.igenericobjectproperties]: undefined
[engineapi.inxdimension]: undefined
[engineapi.inxmeasure]: undefined
[galaxy]: undefined
[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type
[context]: #interface-context