From ec72e8bb4d93f61e377329a03ada20a7ec67eab8 Mon Sep 17 00:00:00 2001 From: Maribeth Bottorff Date: Thu, 1 Sep 2022 11:39:05 -0700 Subject: [PATCH] chore: add api extractor configuration and fix some associated problems (#6388) * chore: add configuration for api extractor * fix: remove extra param names * chore: private to internal * remove unrestricted * chore: remove double backticks * chore: remove fileoverview and export * as * chore: return to returns * chore: fix backslashes and angle brackets in tsdoc * chore: final to sealed * chore: ignore to internal * chore: fix link tags * chore: add api-extractor configuration * chore: add unrecognized tag names * chore: remove tsdoc-metadata * fix: correct index.d.ts * chore: fix connection link --- .gitignore | 2 + api-extractor.json | 390 ++++++++++++++++++++ core/block.ts | 1 - core/block_drag_surface.ts | 2 +- core/blockly.js | 2 +- core/blockly.ts | 2 +- core/common.ts | 4 +- core/connection.ts | 2 +- core/dropdowndiv.ts | 4 +- core/field.ts | 10 +- core/field_textinput.ts | 2 +- core/flyout_base.ts | 9 +- core/flyout_vertical.ts | 2 - core/generator.ts | 6 +- core/interfaces/i_metrics_manager.ts | 2 +- core/menu.ts | 2 +- core/metrics_manager.ts | 2 +- core/names.ts | 4 +- core/renderers/common/constants.ts | 4 +- core/renderers/zelos/info.ts | 2 +- core/utils/colour.ts | 10 +- core/utils/dom.ts | 2 +- core/utils/idgenerator.ts | 6 +- core/variables.ts | 2 +- core/widgetdiv.ts | 4 +- package-lock.json | 533 +++++++++++++++++++++++++++ package.json | 1 + tsconfig.json | 2 + tsdoc.json | 40 ++ typings/blocks.d.ts | 5 - typings/core.d.ts | 5 - typings/dart.d.ts | 5 - typings/index.d.ts | 8 +- typings/javascript.d.ts | 5 - typings/lua.d.ts | 5 - typings/php.d.ts | 5 - typings/python.d.ts | 5 - 37 files changed, 1013 insertions(+), 84 deletions(-) create mode 100644 api-extractor.json create mode 100644 tsdoc.json diff --git a/.gitignore b/.gitignore index 844805ddb..3c1938f17 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ build-debug.log *.pyc *.komodoproject /nbproject/private/ +tsdoc-metadata.json tests/compile/main_compressed.js tests/compile/main_compressed.js.map @@ -18,3 +19,4 @@ local_build/local_*_compressed.js chromedriver build/ dist/ +temp/ diff --git a/api-extractor.json b/api-extractor.json new file mode 100644 index 000000000..bee3a9b8a --- /dev/null +++ b/api-extractor.json @@ -0,0 +1,390 @@ +/** + * Config file for API Extractor. For more info, please visit: https://api-extractor.com + */ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + + /** + * Optionally specifies another JSON config file that this file extends from. This provides a way for + * standard settings to be shared across multiple projects. + * + * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains + * the "extends" field. Otherwise, the first path segment is interpreted as an NPM package name, and will be + * resolved using NodeJS require(). + * + * SUPPORTED TOKENS: none + * DEFAULT VALUE: "" + */ + // "extends": "./shared/api-extractor-base.json" + // "extends": "my-package/include/api-extractor-base.json" + + /** + * Determines the "" token that can be used with other config file settings. The project folder + * typically contains the tsconfig.json and package.json config files, but the path is user-defined. + * + * The path is resolved relative to the folder of the config file that contains the setting. + * + * The default value for "projectFolder" is the token "", which means the folder is determined by traversing + * parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder + * that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error + * will be reported. + * + * SUPPORTED TOKENS: + * DEFAULT VALUE: "" + */ + // "projectFolder": "..", + + /** + * (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis. API Extractor + * analyzes the symbols exported by this module. + * + * The file extension must be ".d.ts" and not ".ts". + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + */ + "mainEntryPointFilePath": "dist/index.d.ts", + + /** + * A list of NPM package names whose exports should be treated as part of this package. + * + * For example, suppose that Webpack is used to generate a distributed bundle for the project "library1", + * and another NPM package "library2" is embedded in this bundle. Some types from library2 may become part + * of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly + * imports library2. To avoid this, we can specify: + * + * "bundledPackages": [ "library2" ], + * + * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been + * local files for library1. + */ + "bundledPackages": [], + + /** + * Determines how the TypeScript compiler engine will be invoked by API Extractor. + */ + "compiler": { + /** + * Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * Note: This setting will be ignored if "overrideTsconfig" is used. + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/tsconfig.json" + */ + // "tsconfigFilePath": "/tsconfig.json", + /** + * Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk. + * The object must conform to the TypeScript tsconfig schema: + * + * http://json.schemastore.org/tsconfig + * + * If omitted, then the tsconfig.json file will be read from the "projectFolder". + * + * DEFAULT VALUE: no overrideTsconfig section + */ + // "overrideTsconfig": { + // . . . + // } + /** + * This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended + * and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when + * dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses + * for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck. + * + * DEFAULT VALUE: false + */ + // "skipLibCheck": true, + }, + + /** + * Configures how the API report file (*.api.md) will be generated. + */ + "apiReport": { + /** + * (REQUIRED) Whether to generate an API report. + */ + "enabled": false, + + /** + * The filename for the API report files. It will be combined with "reportFolder" or "reportTempFolder" to produce + * a full file path. + * + * The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/". + * + * SUPPORTED TOKENS: , + * DEFAULT VALUE: ".api.md" + */ + // "reportFileName": ".api.md", + + /** + * Specifies the folder where the API report file is written. The file name portion is determined by + * the "reportFileName" setting. + * + * The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy, + * e.g. for an API review. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportFolder": "/temp/", + + /** + * Specifies the folder where the temporary report file is written. The file name portion is determined by + * the "reportFileName" setting. + * + * After the temporary file is written to disk, it is compared with the file in the "reportFolder". + * If they are different, a production build will fail. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportTempFolder": "/temp/" + }, + + /** + * Configures how the doc model file (*.api.json) will be generated. + */ + "docModel": { + /** + * (REQUIRED) Whether to generate a doc model file. + */ + "enabled": true + + /** + * The output path for the doc model file. The file extension should be ".api.json". + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/.api.json" + */ + // "apiJsonFilePath": "/temp/.api.json" + }, + + /** + * Configures how the .d.ts rollup file will be generated. + */ + "dtsRollup": { + /** + * (REQUIRED) Whether to generate the .d.ts rollup file. + */ + "enabled": true, + + /** + * Specifies the output path for a .d.ts rollup file to be generated without any trimming. + * This file will include all declarations that are exported by the main entry point. + * + * If the path is an empty string, then this file will not be written. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/dist/.d.ts" + */ + "untrimmedFilePath": "/dist/_rollup.d.ts", + + /** + * Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release. + * This file will include only declarations that are marked as "@public", "@beta", or "@alpha". + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "alphaTrimmedFilePath": "/dist/-alpha.d.ts", + + /** + * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release. + * This file will include only declarations that are marked as "@public" or "@beta". + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "betaTrimmedFilePath": "/dist/-beta.d.ts", + + /** + * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release. + * This file will include only declarations that are marked as "@public". + * + * If the path is an empty string, then this file will not be written. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "publicTrimmedFilePath": "/dist/-public.d.ts", + + /** + * When a declaration is trimmed, by default it will be replaced by a code comment such as + * "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the + * declaration completely. + * + * DEFAULT VALUE: false + */ + // "omitTrimmingComments": true + }, + + /** + * Configures how the tsdoc-metadata.json file will be generated. + */ + "tsdocMetadata": { + /** + * Whether to generate the tsdoc-metadata.json file. + * + * DEFAULT VALUE: true + */ + // "enabled": true, + /** + * Specifies where the TSDoc metadata file should be written. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * The default value is "", which causes the path to be automatically inferred from the "tsdocMetadata", + * "typings" or "main" fields of the project's package.json. If none of these fields are set, the lookup + * falls back to "tsdoc-metadata.json" in the package folder. + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "tsdocMetadataFilePath": "/dist/tsdoc-metadata.json" + }, + + /** + * Specifies what type of newlines API Extractor should use when writing output files. By default, the output files + * will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead. + * To use the OS's default newline kind, specify "os". + * + * DEFAULT VALUE: "crlf" + */ + // "newlineKind": "crlf", + + /** + * Configures how API Extractor reports error and warning messages produced during analysis. + * + * There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages. + */ + "messages": { + /** + * Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing + * the input .d.ts files. + * + * TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551" + * + * DEFAULT VALUE: A single "default" entry with logLevel=warning. + */ + "compilerMessageReporting": { + /** + * Configures the default routing for messages that don't match an explicit rule in this table. + */ + "default": { + /** + * Specifies whether the message should be written to the the tool's output log. Note that + * the "addToApiReportFile" property may supersede this option. + * + * Possible values: "error", "warning", "none" + * + * Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail + * and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes + * the "--local" option), the warning is displayed but the build will not fail. + * + * DEFAULT VALUE: "warning" + */ + "logLevel": "warning" + + /** + * When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md), + * then the message will be written inside that file; otherwise, the message is instead logged according to + * the "logLevel" option. + * + * DEFAULT VALUE: false + */ + // "addToApiReportFile": false + } + + // "TS2551": { + // "logLevel": "warning", + // "addToApiReportFile": true + // }, + // + // . . . + }, + + /** + * Configures handling of messages reported by API Extractor during its analysis. + * + * API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag" + * + * DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings + */ + "extractorMessageReporting": { + "default": { + "logLevel": "warning" + // "addToApiReportFile": false + }, + + // We don't use `@public`, that's just the default. + "ae-missing-release-tag": { + "logLevel": "none" + }, + + // Needs investigation. + "ae-forgotten-export": { + "logLevel": "none" + } + }, + + /** + * Configures handling of messages reported by the TSDoc parser when analyzing code comments. + * + * TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text" + * + * DEFAULT VALUE: A single "default" entry with logLevel=warning. + */ + "tsdocMessageReporting": { + "default": { + "logLevel": "warning" + // "addToApiReportFile": false + }, + + "tsdoc-param-tag-missing-hyphen": { + "logLevel": "none" + }, + + // These two are due to "type-like" tags in JsDoc like + // `@suppress {warningName}`. The braces are unexpected in TsDoc. + "tsdoc-malformed-inline-tag": { + "logLevel": "none" + }, + "tsdoc-escape-right-brace": { + "logLevel": "none" + }, + + // Needs to be fixed + "tsdoc-missing-deprecation-message": { + "logLevel": "none" + } + } + } +} diff --git a/core/block.ts b/core/block.ts index d3931094a..1970a241e 100644 --- a/core/block.ts +++ b/core/block.ts @@ -51,7 +51,6 @@ import type {Workspace} from './workspace.js'; * Class for one block. * Not normally called directly, workspace.newBlock() is preferred. * - * @unrestricted * @alias Blockly.Block */ export class Block implements IASTNodeLocation, IDeletable { diff --git a/core/block_drag_surface.ts b/core/block_drag_surface.ts index 7238e6313..092bbb820 100644 --- a/core/block_drag_surface.ts +++ b/core/block_drag_surface.ts @@ -121,7 +121,7 @@ export class BlockDragSurfaceSvg { /** * Translate the drag surface's SVG based on its internal state. * - * @private + * @internal */ translateSurfaceInternal_() { let x = this.surfaceXY_!.x; diff --git a/core/blockly.js b/core/blockly.js index 96878e606..59e995451 100644 --- a/core/blockly.js +++ b/core/blockly.js @@ -335,7 +335,7 @@ exports.defineBlocksWithJsonArray = common.defineBlocksWithJsonArray; * Set the parent container. This is the container element that the WidgetDiv, * dropDownDiv, and Tooltip are rendered into the first time `Blockly.inject` * is called. - * This method is a NOP if called after the first ``Blockly.inject``. + * This method is a NOP if called after the first `Blockly.inject`. * @param {!Element} container The container element. * @see Blockly.common.setParentContainer * @alias Blockly.setParentContainer diff --git a/core/blockly.ts b/core/blockly.ts index 7f51f06fa..052c606ba 100644 --- a/core/blockly.ts +++ b/core/blockly.ts @@ -337,7 +337,7 @@ export const defineBlocksWithJsonArray = common.defineBlocksWithJsonArray; * Set the parent container. This is the container element that the WidgetDiv, * dropDownDiv, and Tooltip are rendered into the first time `Blockly.inject` * is called. - * This method is a NOP if called after the first ``Blockly.inject``. + * This method is a NOP if called after the first `Blockly.inject`. * * @param container The container element. * @see Blockly.common.setParentContainer diff --git a/core/common.ts b/core/common.ts index 18f255d3f..3181e88e7 100644 --- a/core/common.ts +++ b/core/common.ts @@ -128,7 +128,7 @@ export function setSelected(newSelection: ICopyable|null) { let parentContainer: Element|null; /** - * Get the container element in which to render the WidgetDiv, DropDownDiv and\ + * Get the container element in which to render the WidgetDiv, DropDownDiv and * Tooltip. * * @returns The parent container. @@ -142,7 +142,7 @@ export function getParentContainer(): Element|null { * Set the parent container. This is the container element that the WidgetDiv, * DropDownDiv, and Tooltip are rendered into the first time `Blockly.inject` * is called. - * This method is a NOP if called after the first ``Blockly.inject``. + * This method is a NOP if called after the first `Blockly.inject`. * * @param newParent The container element. * @alias Blockly.common.setParentContainer diff --git a/core/connection.ts b/core/connection.ts index 73f86737f..8abf5e89b 100644 --- a/core/connection.ts +++ b/core/connection.ts @@ -427,7 +427,7 @@ export class Connection implements IASTNodeLocationWithBlock { * * Headless configurations (the default) do not have neighboring connection, * and always return an empty list (the default). - * {@link Blockly.RenderedConnection} overrides this behavior with a list + * {@link RenderedConnection#neighbours} overrides this behavior with a list * computed from the rendered positioning. * * @param _maxLimit The maximum radius to another connection. diff --git a/core/dropdowndiv.ts b/core/dropdowndiv.ts index 6bc2a9106..d86a9af0c 100644 --- a/core/dropdowndiv.ts +++ b/core/dropdowndiv.ts @@ -329,7 +329,7 @@ const internal = { /** * Get sizing info about the bounding element. * - * @return An object containing size information about the bounding element + * @returns An object containing size information about the bounding element * (bounding box and width/height). */ getBoundsInfo: function(): BoundsInfo { @@ -354,7 +354,7 @@ const internal = { * @param primaryY Desired origin point y, in absolute px. * @param secondaryX Secondary/alternative origin point x, in absolute px. * @param secondaryY Secondary/alternative origin point y, in absolute px. - * @return Various final metrics, including rendered positions for drop-down + * @returns Various final metrics, including rendered positions for drop-down * and arrow. */ getPositionMetrics: function( diff --git a/core/field.ts b/core/field.ts index 059ec0326..981330f76 100644 --- a/core/field.ts +++ b/core/field.ts @@ -280,7 +280,7 @@ export abstract class Field implements IASTNodeLocationSvg, * Initialize everything to render this field. Override * methods initModel and initView rather than this method. * - * @final + * @sealed * @internal */ init() { @@ -662,7 +662,7 @@ export abstract class Field implements IASTNodeLocationSvg, * * @param opt_e Optional mouse event that triggered the field to open, or * undefined if triggered programmatically. - * @final + * @sealed * @internal */ showEditor(opt_e?: Event) { @@ -833,7 +833,7 @@ export abstract class Field implements IASTNodeLocationSvg, /** * Get the text from this field to display on the block. May differ from - * ``getText`` due to ellipsis, and other formatting. + * `getText` due to ellipsis, and other formatting. * * @returns Text to display. */ @@ -862,7 +862,7 @@ export abstract class Field implements IASTNodeLocationSvg, * value to a string. * * @returns Current text. - * @final + * @sealed */ getText(): string { // this.getText_ was intended so that devs don't have to remember to call @@ -924,7 +924,7 @@ export abstract class Field implements IASTNodeLocationSvg, * than this method. * * @param newValue New value. - * @final + * @sealed */ setValue(newValue: AnyDuringMigration) { const doLogging = false; diff --git a/core/field_textinput.ts b/core/field_textinput.ts index 386e8bdd2..d1a66e268 100644 --- a/core/field_textinput.ts +++ b/core/field_textinput.ts @@ -486,7 +486,7 @@ export class FieldTextInput extends Field { /** * Set the HTML input value and the field's internal value. The difference - * between this and ``setValue`` is that this also updates the HTML input + * between this and `setValue` is that this also updates the HTML input * value whilst editing. * * @param newValue New value. diff --git a/core/flyout_base.ts b/core/flyout_base.ts index 223d930da..150df13cf 100644 --- a/core/flyout_base.ts +++ b/core/flyout_base.ts @@ -220,11 +220,16 @@ export abstract class Flyout extends DeleteArea implements IFlyout { * workspace". Drags that are within the bounds of this many degrees from * the orthogonal line to the flyout edge are considered to be "drags toward * the workspace". - * Example: + * + * @example + * + * ``` * Flyout Edge Workspace * [block] / <-within this angle, drags "toward workspace" | * [block] ---- orthogonal to flyout boundary ---- | * [block] \ | + * ``` + * * The angle is given in degrees from the orthogonal. * * This is used to know when to create a new block and when to scroll the @@ -1035,10 +1040,8 @@ export abstract class Flyout extends DeleteArea implements IFlyout { * @param y The y position of the cursor during this layout pass. * @param blockHW The height and width of * the block. - * @param blockHW.height * @param index The index into the mats list where this rect should * be placed. - * @param blockHW.width * @returns Newly created SVG element for the rectangle behind * the block. */ diff --git a/core/flyout_vertical.ts b/core/flyout_vertical.ts index 860379b77..fa9d1ad39 100644 --- a/core/flyout_vertical.ts +++ b/core/flyout_vertical.ts @@ -44,8 +44,6 @@ export class VerticalFlyout extends Flyout { * * @param xyRatio Contains a y property which is a float between 0 and 1 * specifying the degree of scrolling and a similar x property. - * @param xyRatio.x - * @param xyRatio.y */ protected override setMetrics_(xyRatio: {x: number, y: number}) { if (!this.isVisible()) { diff --git a/core/generator.ts b/core/generator.ts index 62d884daf..443af0ff8 100644 --- a/core/generator.ts +++ b/core/generator.ts @@ -41,21 +41,21 @@ export class Generator { /** * Arbitrary code to inject into locations that risk causing infinite loops. * Any instances of '%1' will be replaced by the block ID that failed. - * E.g. ' checkTimeout(%1);\n' + * E.g. ` checkTimeout(%1);\n` */ INFINITE_LOOP_TRAP: string|null = null; /** * Arbitrary code to inject before every statement. * Any instances of '%1' will be replaced by the block ID of the statement. - * E.g. 'highlight(%1);\n' + * E.g. `highlight(%1);\n` */ STATEMENT_PREFIX: string|null = null; /** * Arbitrary code to inject after every statement. * Any instances of '%1' will be replaced by the block ID of the statement. - * E.g. 'highlight(%1);\n' + * E.g. `highlight(%1);\n` */ STATEMENT_SUFFIX: string|null = null; diff --git a/core/interfaces/i_metrics_manager.ts b/core/interfaces/i_metrics_manager.ts index 3988c4a85..923ad8035 100644 --- a/core/interfaces/i_metrics_manager.ts +++ b/core/interfaces/i_metrics_manager.ts @@ -61,7 +61,7 @@ export interface IMetricsManager { * pixel coordinates. Returns 0 for the width and height if the workspace has * a simple toolbox instead of a category toolbox. To get the width and height * of a - * simple toolbox @see {@link getFlyoutMetrics}. + * simple toolbox @see {@link IMetricsManager#getFlyoutMetrics}. * * @returns The object with the width, height and position of the toolbox. */ diff --git a/core/menu.ts b/core/menu.ts index a3b316a37..e3612cede 100644 --- a/core/menu.ts +++ b/core/menu.ts @@ -381,7 +381,7 @@ export class Menu { /** * Attempts to handle a keyboard event, if the menu item is enabled, by * calling - * {@link handleKeyEventInternal_}. + * {@link Menu#handleKeyEventInternal_}. * * @param e Key event to handle. */ diff --git a/core/metrics_manager.ts b/core/metrics_manager.ts index 6d4329eb5..7d8ba5cf9 100644 --- a/core/metrics_manager.ts +++ b/core/metrics_manager.ts @@ -77,7 +77,7 @@ export class MetricsManager implements IMetricsManager { * pixel coordinates. Returns 0 for the width and height if the workspace has * a simple toolbox instead of a category toolbox. To get the width and height * of a - * simple toolbox @see {@link getFlyoutMetrics}. + * simple toolbox @see {@link MetricsManager#getFlyoutMetrics}. * * @returns The object with the width, height and position of the toolbox. */ diff --git a/core/names.ts b/core/names.ts index 0a656fbcf..b6b026fd3 100644 --- a/core/names.ts +++ b/core/names.ts @@ -248,8 +248,8 @@ export namespace Names { * procedure 'foo' would collide. However, Blockly has no such problems since * variable get 'foo' and procedure call 'foo' are unambiguous. * Therefore, Blockly keeps a separate name type to disambiguate. - * getName('foo', 'VARIABLE') -> 'foo' - * getName('foo', 'PROCEDURE') -> 'foo2' + * getName('foo', 'VARIABLE') = 'foo' + * getName('foo', 'PROCEDURE') = 'foo2' * * @alias Blockly.Names.NameType */ diff --git a/core/renderers/common/constants.ts b/core/renderers/common/constants.ts index 66312364f..75063f9b4 100644 --- a/core/renderers/common/constants.ts +++ b/core/renderers/common/constants.ts @@ -204,13 +204,13 @@ export class ConstantProvider { /** * Height of text. This constant is dynamically set in - * ``setFontConstants_`` to be the height of the text based on the font + * `setFontConstants_` to be the height of the text based on the font * used. */ FIELD_TEXT_HEIGHT = -1; // Dynamically set. /** - * Text baseline. This constant is dynamically set in ``setFontConstants_`` + * Text baseline. This constant is dynamically set in `setFontConstants_` * to be the baseline of the text based on the font used. */ FIELD_TEXT_BASELINE = -1; // Dynamically set. diff --git a/core/renderers/zelos/info.ts b/core/renderers/zelos/info.ts index 99945dc38..82bdec730 100644 --- a/core/renderers/zelos/info.ts +++ b/core/renderers/zelos/info.ts @@ -296,7 +296,7 @@ export class RenderInfo extends BaseRenderInfo { /** * Adjust the x position of fields to bump all non-label fields in the first - * row past the notch position. This must be called before ``computeBounds`` + * row past the notch position. This must be called before `computeBounds` * is called. */ protected adjustXPosition_() { diff --git a/core/utils/colour.ts b/core/utils/colour.ts index 41dbb0dd0..fad93adb8 100644 --- a/core/utils/colour.ts +++ b/core/utils/colour.ts @@ -77,11 +77,11 @@ export function setHsvValue(newValue: number) { /** * Parses a colour from a string. - * .parse('red') -> '#ff0000' - * .parse('#f00') -> '#ff0000' - * .parse('#ff0000') -> '#ff0000' - * .parse('0xff0000') -> '#ff0000' - * .parse('rgb(255, 0, 0)') -> '#ff0000' + * .parse('red') = '#ff0000' + * .parse('#f00') = '#ff0000' + * .parse('#ff0000') = '#ff0000' + * .parse('0xff0000') = '#ff0000' + * .parse('rgb(255, 0, 0)') = '#ff0000' * * @param str Colour in some CSS format. * @returns A string containing a hex representation of the colour, or null if diff --git a/core/utils/dom.ts b/core/utils/dom.ts index a74e8cad5..2db279b43 100644 --- a/core/utils/dom.ts +++ b/core/utils/dom.ts @@ -312,7 +312,7 @@ export function getFastTextWidth( * Gets the width of a text element using a faster method than `getTextWidth`. * This method requires that we know the text element's font family and size in * advance. Similar to `getTextWidth`, we cache the width we compute. - * This method is similar to ``getFastTextWidth`` but expects the font size + * This method is similar to `getFastTextWidth` but expects the font size * parameter to be a string. * * @param textElement An SVG 'text' element. diff --git a/core/utils/idgenerator.ts b/core/utils/idgenerator.ts index 4fe0aa67c..4f4735608 100644 --- a/core/utils/idgenerator.ts +++ b/core/utils/idgenerator.ts @@ -24,14 +24,14 @@ const soup = '!#$%()*+,-./:;=?@[]^_`{|}~' + /** * Namespace object for internal implementations we want to be able to - * stub in tests. + * stub in tests. Do not use externally. * - * @ignore + * @internal */ const internal = { /** * Generate a random unique ID. This should be globally unique. - * 87 characters ^ 20 length > 128 bits (better than a UUID). + * 87 characters ^ 20 length is greater than 128 bits (better than a UUID). * * @returns A globally unique ID string. */ diff --git a/core/variables.ts b/core/variables.ts index 56768a79e..b3a15584d 100644 --- a/core/variables.ts +++ b/core/variables.ts @@ -193,7 +193,7 @@ function generateUniqueNameInternal(workspace: Workspace): string { /** * Returns a unique name that is not present in the usedNames array. This - * will try to generate single letter names in the range a -> z (skip l). It + * will try to generate single letter names in the range a - z (skip l). It * will start with the character passed to startChar. * * @param startChar The character to start the search at. diff --git a/core/widgetdiv.ts b/core/widgetdiv.ts index f66c3d638..85fbee2e6 100644 --- a/core/widgetdiv.ts +++ b/core/widgetdiv.ts @@ -47,11 +47,11 @@ export function getDiv(): HTMLDivElement|null { } /** - * Allows unit tests to reset the div. + * Allows unit tests to reset the div. Do not use outside of tests. * * @param newDiv The new value for the DIV field. * @alias Blockly.WidgetDiv.testOnly_setDiv - * @ignore + * @internal */ export function testOnly_setDiv(newDiv: HTMLDivElement|null) { containerDiv = newDiv; diff --git a/package-lock.json b/package-lock.json index d2919147d..06446a4d9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -16,6 +16,7 @@ "@blockly/dev-tools": "^4.0.2", "@blockly/theme-modern": "^2.1.1", "@hyperjump/json-schema": "^0.18.4", + "@microsoft/api-extractor": "^7.29.5", "@typescript-eslint/eslint-plugin": "^5.33.1", "@wdio/selenium-standalone-service": "^7.10.1", "chai": "^4.2.0", @@ -489,6 +490,92 @@ "url": "https://github.com/sponsors/jdesrosiers" } }, + "node_modules/@microsoft/api-extractor": { + "version": "7.29.5", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor/-/api-extractor-7.29.5.tgz", + "integrity": "sha512-+vqO/TAGw9xXANpvTjA4y5ADcaRuYuBoJ9IfoAHubrGuxKG6GoW3P2tfdgwteLz95CnlftBxYp+3NG/mf05P9Q==", + "dev": true, + "dependencies": { + "@microsoft/api-extractor-model": "7.23.3", + "@microsoft/tsdoc": "0.14.1", + "@microsoft/tsdoc-config": "~0.16.1", + "@rushstack/node-core-library": "3.51.1", + "@rushstack/rig-package": "0.3.14", + "@rushstack/ts-command-line": "4.12.2", + "colors": "~1.2.1", + "lodash": "~4.17.15", + "resolve": "~1.17.0", + "semver": "~7.3.0", + "source-map": "~0.6.1", + "typescript": "~4.7.4" + }, + "bin": { + "api-extractor": "bin/api-extractor" + } + }, + "node_modules/@microsoft/api-extractor-model": { + "version": "7.23.3", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor-model/-/api-extractor-model-7.23.3.tgz", + "integrity": "sha512-HpsWzG6jrWHrTlIg53kmp/IVQPBHUZc+8dunnr9VXrmDjVBehaXxp9A6jhTQ/bd7W1m5TYfAvwCmseC1+9FCuA==", + "dev": true, + "dependencies": { + "@microsoft/tsdoc": "0.14.1", + "@microsoft/tsdoc-config": "~0.16.1", + "@rushstack/node-core-library": "3.51.1" + } + }, + "node_modules/@microsoft/api-extractor/node_modules/resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "dependencies": { + "path-parse": "^1.0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/@microsoft/api-extractor/node_modules/source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/@microsoft/tsdoc": { + "version": "0.14.1", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc/-/tsdoc-0.14.1.tgz", + "integrity": "sha512-6Wci+Tp3CgPt/B9B0a3J4s3yMgLNSku6w5TV6mN+61C71UqsRBv2FUibBf3tPGlNxebgPHMEUzKpb1ggE8KCKw==", + "dev": true + }, + "node_modules/@microsoft/tsdoc-config": { + "version": "0.16.1", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc-config/-/tsdoc-config-0.16.1.tgz", + "integrity": "sha512-2RqkwiD4uN6MLnHFljqBlZIXlt/SaUT6cuogU1w2ARw4nKuuppSmR0+s+NC+7kXBQykd9zzu0P4HtBpZT5zBpQ==", + "dev": true, + "dependencies": { + "@microsoft/tsdoc": "0.14.1", + "ajv": "~6.12.6", + "jju": "~1.4.0", + "resolve": "~1.19.0" + } + }, + "node_modules/@microsoft/tsdoc-config/node_modules/resolve": { + "version": "1.19.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.19.0.tgz", + "integrity": "sha512-rArEXAgsBG4UgRGcynxWIWKFvh/XZCcS8UJdHhwy91zwAvCZIbcs+vAbflgBnNjYMs/i/i+/Ux6IZhML1yPvxg==", + "dev": true, + "dependencies": { + "is-core-module": "^2.1.0", + "path-parse": "^1.0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, "node_modules/@nodelib/fs.scandir": { "version": "2.1.5", "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", @@ -524,6 +611,115 @@ "node": ">= 8" } }, + "node_modules/@rushstack/node-core-library": { + "version": "3.51.1", + "resolved": "https://registry.npmjs.org/@rushstack/node-core-library/-/node-core-library-3.51.1.tgz", + "integrity": "sha512-xLoUztvGpaT5CphDexDPt2WbBx8D68VS5tYOkwfr98p90y0f/wepgXlTA/q5MUeZGGucASiXKp5ysdD+GPYf9A==", + "dev": true, + "dependencies": { + "@types/node": "12.20.24", + "colors": "~1.2.1", + "fs-extra": "~7.0.1", + "import-lazy": "~4.0.0", + "jju": "~1.4.0", + "resolve": "~1.17.0", + "semver": "~7.3.0", + "z-schema": "~5.0.2" + } + }, + "node_modules/@rushstack/node-core-library/node_modules/@types/node": { + "version": "12.20.24", + "resolved": "https://registry.npmjs.org/@types/node/-/node-12.20.24.tgz", + "integrity": "sha512-yxDeaQIAJlMav7fH5AQqPH1u8YIuhYJXYBzxaQ4PifsU0GDO38MSdmEDeRlIxrKbC6NbEaaEHDanWb+y30U8SQ==", + "dev": true + }, + "node_modules/@rushstack/node-core-library/node_modules/fs-extra": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz", + "integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.2", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, + "node_modules/@rushstack/node-core-library/node_modules/jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==", + "dev": true, + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, + "node_modules/@rushstack/node-core-library/node_modules/resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "dependencies": { + "path-parse": "^1.0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/@rushstack/node-core-library/node_modules/universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "dev": true, + "engines": { + "node": ">= 4.0.0" + } + }, + "node_modules/@rushstack/rig-package": { + "version": "0.3.14", + "resolved": "https://registry.npmjs.org/@rushstack/rig-package/-/rig-package-0.3.14.tgz", + "integrity": "sha512-Ic9EN3kWJCK6iOxEDtwED9nrM146zCDrQaUxbeGOF+q/VLZ/HNHPw+aLqrqmTl0ZT66Sf75Qk6OG+rySjTorvQ==", + "dev": true, + "dependencies": { + "resolve": "~1.17.0", + "strip-json-comments": "~3.1.1" + } + }, + "node_modules/@rushstack/rig-package/node_modules/resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "dependencies": { + "path-parse": "^1.0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/@rushstack/ts-command-line": { + "version": "4.12.2", + "resolved": "https://registry.npmjs.org/@rushstack/ts-command-line/-/ts-command-line-4.12.2.tgz", + "integrity": "sha512-poBtnumLuWmwmhCEkVAgynWgtnF9Kygekxyp4qtQUSbBrkuyPQTL85c8Cva1YfoUpOdOXxezMAkUt0n5SNKGqw==", + "dev": true, + "dependencies": { + "@types/argparse": "1.0.38", + "argparse": "~1.0.9", + "colors": "~1.2.1", + "string-argv": "~0.3.1" + } + }, + "node_modules/@rushstack/ts-command-line/node_modules/argparse": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "dev": true, + "dependencies": { + "sprintf-js": "~1.0.2" + } + }, "node_modules/@sindresorhus/is": { "version": "4.2.0", "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-4.2.0.tgz", @@ -583,6 +779,12 @@ "node": ">=10" } }, + "node_modules/@types/argparse": { + "version": "1.0.38", + "resolved": "https://registry.npmjs.org/@types/argparse/-/argparse-1.0.38.tgz", + "integrity": "sha512-ebDJ9b0e702Yr7pWgB0jzm+CX4Srzz8RcXtLJDJB+BSccqMa36uyH/zUsSYao5+BD1ytv3k3rPYCq4mAE1hsXA==", + "dev": true + }, "node_modules/@types/aria-query": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.0.tgz", @@ -3217,6 +3419,15 @@ "color-support": "bin.js" } }, + "node_modules/colors": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.2.5.tgz", + "integrity": "sha512-erNRLao/Y3Fv54qUa0LBB+//Uf3YwMUmdJinN20yMXm9zdKKqH9wt7R9IIVZ+K7ShzfpLV/Zg8+VyrBJYB4lpg==", + "dev": true, + "engines": { + "node": ">=0.1.90" + } + }, "node_modules/combined-stream": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", @@ -7010,6 +7221,15 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/import-lazy": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/import-lazy/-/import-lazy-4.0.0.tgz", + "integrity": "sha512-rKtvo6a868b5Hu3heneU+L4yEQ4jYKLtjpnPeUdK7h0yzXGmyBTypknlkCvHFBqfX9YlorEiMM6Dnq/5atfHkw==", + "dev": true, + "engines": { + "node": ">=8" + } + }, "node_modules/imurmurhash": { "version": "0.1.4", "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz", @@ -7596,6 +7816,12 @@ "node": ">=4" } }, + "node_modules/jju": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/jju/-/jju-1.4.0.tgz", + "integrity": "sha512-8wb9Yw966OSxApiCt0K3yNJL8pnNeIv+OEq2YMidz4FKP6nonSRoOXc80iXY4JaN2FC11B9qsNmDsm+ZOfMROA==", + "dev": true + }, "node_modules/js-green-licenses": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/js-green-licenses/-/js-green-licenses-3.0.1.tgz", @@ -8131,6 +8357,12 @@ "integrity": "sha1-eeTriMNqgSKvhvhEqpvNhRtfu1U=", "dev": true }, + "node_modules/lodash.isequal": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", + "integrity": "sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==", + "dev": true + }, "node_modules/lodash.isobject": { "version": "3.0.2", "resolved": "https://registry.npmjs.org/lodash.isobject/-/lodash.isobject-3.0.2.tgz", @@ -11526,6 +11758,12 @@ "node": ">=0.10.0" } }, + "node_modules/sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==", + "dev": true + }, "node_modules/sshpk": { "version": "1.16.1", "resolved": "https://registry.npmjs.org/sshpk/-/sshpk-1.16.1.tgz", @@ -11740,6 +11978,15 @@ "safe-buffer": "~5.1.0" } }, + "node_modules/string-argv": { + "version": "0.3.1", + "resolved": "https://registry.npmjs.org/string-argv/-/string-argv-0.3.1.tgz", + "integrity": "sha512-a1uQGz7IyVy9YwhqjZIZu1c8JO8dNIe20xBmSS6qu9kv++k3JGzCVmprbNN5Kn+BgzD5E7YYwg1CcjuJMRNsvg==", + "dev": true, + "engines": { + "node": ">=0.6.19" + } + }, "node_modules/string-width": { "version": "4.2.3", "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", @@ -12555,6 +12802,15 @@ "builtins": "^1.0.3" } }, + "node_modules/validator": { + "version": "13.7.0", + "resolved": "https://registry.npmjs.org/validator/-/validator-13.7.0.tgz", + "integrity": "sha512-nYXQLCBkpJ8X6ltALua9dRrZDHVYxjJ1wgskNt1lH9fzGjs3tgojGSCBjmEPwkWS1y29+DrizMTW19Pr9uB2nw==", + "dev": true, + "engines": { + "node": ">= 0.10" + } + }, "node_modules/value-or-function": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/value-or-function/-/value-or-function-3.0.0.tgz", @@ -13399,6 +13655,33 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/z-schema": { + "version": "5.0.3", + "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.3.tgz", + "integrity": "sha512-sGvEcBOTNum68x9jCpCVGPFJ6mWnkD0YxOcddDlJHRx3tKdB2q8pCHExMVZo/AV/6geuVJXG7hljDaWG8+5GDw==", + "dev": true, + "dependencies": { + "lodash.get": "^4.4.2", + "lodash.isequal": "^4.5.0", + "validator": "^13.7.0" + }, + "bin": { + "z-schema": "bin/z-schema" + }, + "engines": { + "node": ">=8.0.0" + }, + "optionalDependencies": { + "commander": "^2.20.3" + } + }, + "node_modules/z-schema/node_modules/commander": { + "version": "2.20.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", + "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", + "dev": true, + "optional": true + }, "node_modules/zip-stream": { "version": "4.1.0", "resolved": "https://registry.npmjs.org/zip-stream/-/zip-stream-4.1.0.tgz", @@ -13752,6 +14035,84 @@ "just-curry-it": "^3.1.0" } }, + "@microsoft/api-extractor": { + "version": "7.29.5", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor/-/api-extractor-7.29.5.tgz", + "integrity": "sha512-+vqO/TAGw9xXANpvTjA4y5ADcaRuYuBoJ9IfoAHubrGuxKG6GoW3P2tfdgwteLz95CnlftBxYp+3NG/mf05P9Q==", + "dev": true, + "requires": { + "@microsoft/api-extractor-model": "7.23.3", + "@microsoft/tsdoc": "0.14.1", + "@microsoft/tsdoc-config": "~0.16.1", + "@rushstack/node-core-library": "3.51.1", + "@rushstack/rig-package": "0.3.14", + "@rushstack/ts-command-line": "4.12.2", + "colors": "~1.2.1", + "lodash": "~4.17.15", + "resolve": "~1.17.0", + "semver": "~7.3.0", + "source-map": "~0.6.1", + "typescript": "~4.7.4" + }, + "dependencies": { + "resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "requires": { + "path-parse": "^1.0.6" + } + }, + "source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "dev": true + } + } + }, + "@microsoft/api-extractor-model": { + "version": "7.23.3", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor-model/-/api-extractor-model-7.23.3.tgz", + "integrity": "sha512-HpsWzG6jrWHrTlIg53kmp/IVQPBHUZc+8dunnr9VXrmDjVBehaXxp9A6jhTQ/bd7W1m5TYfAvwCmseC1+9FCuA==", + "dev": true, + "requires": { + "@microsoft/tsdoc": "0.14.1", + "@microsoft/tsdoc-config": "~0.16.1", + "@rushstack/node-core-library": "3.51.1" + } + }, + "@microsoft/tsdoc": { + "version": "0.14.1", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc/-/tsdoc-0.14.1.tgz", + "integrity": "sha512-6Wci+Tp3CgPt/B9B0a3J4s3yMgLNSku6w5TV6mN+61C71UqsRBv2FUibBf3tPGlNxebgPHMEUzKpb1ggE8KCKw==", + "dev": true + }, + "@microsoft/tsdoc-config": { + "version": "0.16.1", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc-config/-/tsdoc-config-0.16.1.tgz", + "integrity": "sha512-2RqkwiD4uN6MLnHFljqBlZIXlt/SaUT6cuogU1w2ARw4nKuuppSmR0+s+NC+7kXBQykd9zzu0P4HtBpZT5zBpQ==", + "dev": true, + "requires": { + "@microsoft/tsdoc": "0.14.1", + "ajv": "~6.12.6", + "jju": "~1.4.0", + "resolve": "~1.19.0" + }, + "dependencies": { + "resolve": { + "version": "1.19.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.19.0.tgz", + "integrity": "sha512-rArEXAgsBG4UgRGcynxWIWKFvh/XZCcS8UJdHhwy91zwAvCZIbcs+vAbflgBnNjYMs/i/i+/Ux6IZhML1yPvxg==", + "dev": true, + "requires": { + "is-core-module": "^2.1.0", + "path-parse": "^1.0.6" + } + } + } + }, "@nodelib/fs.scandir": { "version": "2.1.5", "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", @@ -13778,6 +14139,109 @@ "fastq": "^1.6.0" } }, + "@rushstack/node-core-library": { + "version": "3.51.1", + "resolved": "https://registry.npmjs.org/@rushstack/node-core-library/-/node-core-library-3.51.1.tgz", + "integrity": "sha512-xLoUztvGpaT5CphDexDPt2WbBx8D68VS5tYOkwfr98p90y0f/wepgXlTA/q5MUeZGGucASiXKp5ysdD+GPYf9A==", + "dev": true, + "requires": { + "@types/node": "12.20.24", + "colors": "~1.2.1", + "fs-extra": "~7.0.1", + "import-lazy": "~4.0.0", + "jju": "~1.4.0", + "resolve": "~1.17.0", + "semver": "~7.3.0", + "z-schema": "~5.0.2" + }, + "dependencies": { + "@types/node": { + "version": "12.20.24", + "resolved": "https://registry.npmjs.org/@types/node/-/node-12.20.24.tgz", + "integrity": "sha512-yxDeaQIAJlMav7fH5AQqPH1u8YIuhYJXYBzxaQ4PifsU0GDO38MSdmEDeRlIxrKbC6NbEaaEHDanWb+y30U8SQ==", + "dev": true + }, + "fs-extra": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz", + "integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.2", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + } + }, + "jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.6" + } + }, + "resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "requires": { + "path-parse": "^1.0.6" + } + }, + "universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "dev": true + } + } + }, + "@rushstack/rig-package": { + "version": "0.3.14", + "resolved": "https://registry.npmjs.org/@rushstack/rig-package/-/rig-package-0.3.14.tgz", + "integrity": "sha512-Ic9EN3kWJCK6iOxEDtwED9nrM146zCDrQaUxbeGOF+q/VLZ/HNHPw+aLqrqmTl0ZT66Sf75Qk6OG+rySjTorvQ==", + "dev": true, + "requires": { + "resolve": "~1.17.0", + "strip-json-comments": "~3.1.1" + }, + "dependencies": { + "resolve": { + "version": "1.17.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.17.0.tgz", + "integrity": "sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==", + "dev": true, + "requires": { + "path-parse": "^1.0.6" + } + } + } + }, + "@rushstack/ts-command-line": { + "version": "4.12.2", + "resolved": "https://registry.npmjs.org/@rushstack/ts-command-line/-/ts-command-line-4.12.2.tgz", + "integrity": "sha512-poBtnumLuWmwmhCEkVAgynWgtnF9Kygekxyp4qtQUSbBrkuyPQTL85c8Cva1YfoUpOdOXxezMAkUt0n5SNKGqw==", + "dev": true, + "requires": { + "@types/argparse": "1.0.38", + "argparse": "~1.0.9", + "colors": "~1.2.1", + "string-argv": "~0.3.1" + }, + "dependencies": { + "argparse": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "dev": true, + "requires": { + "sprintf-js": "~1.0.2" + } + } + } + }, "@sindresorhus/is": { "version": "4.2.0", "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-4.2.0.tgz", @@ -13828,6 +14292,12 @@ "defer-to-connect": "^2.0.0" } }, + "@types/argparse": { + "version": "1.0.38", + "resolved": "https://registry.npmjs.org/@types/argparse/-/argparse-1.0.38.tgz", + "integrity": "sha512-ebDJ9b0e702Yr7pWgB0jzm+CX4Srzz8RcXtLJDJB+BSccqMa36uyH/zUsSYao5+BD1ytv3k3rPYCq4mAE1hsXA==", + "dev": true + }, "@types/aria-query": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.0.tgz", @@ -15844,6 +16314,12 @@ "integrity": "sha512-qiBjkpbMLO/HL68y+lh4q0/O1MZFj2RX6X/KmMa3+gJD3z+WwI1ZzDHysvqHGS3mP6mznPckpXmw1nI9cJjyRg==", "dev": true }, + "colors": { + "version": "1.2.5", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.2.5.tgz", + "integrity": "sha512-erNRLao/Y3Fv54qUa0LBB+//Uf3YwMUmdJinN20yMXm9zdKKqH9wt7R9IIVZ+K7ShzfpLV/Zg8+VyrBJYB4lpg==", + "dev": true + }, "combined-stream": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", @@ -18890,6 +19366,12 @@ "resolve-from": "^4.0.0" } }, + "import-lazy": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/import-lazy/-/import-lazy-4.0.0.tgz", + "integrity": "sha512-rKtvo6a868b5Hu3heneU+L4yEQ4jYKLtjpnPeUdK7h0yzXGmyBTypknlkCvHFBqfX9YlorEiMM6Dnq/5atfHkw==", + "dev": true + }, "imurmurhash": { "version": "0.1.4", "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz", @@ -19341,6 +19823,12 @@ } } }, + "jju": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/jju/-/jju-1.4.0.tgz", + "integrity": "sha512-8wb9Yw966OSxApiCt0K3yNJL8pnNeIv+OEq2YMidz4FKP6nonSRoOXc80iXY4JaN2FC11B9qsNmDsm+ZOfMROA==", + "dev": true + }, "js-green-licenses": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/js-green-licenses/-/js-green-licenses-3.0.1.tgz", @@ -19802,6 +20290,12 @@ "integrity": "sha1-eeTriMNqgSKvhvhEqpvNhRtfu1U=", "dev": true }, + "lodash.isequal": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", + "integrity": "sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==", + "dev": true + }, "lodash.isobject": { "version": "3.0.2", "resolved": "https://registry.npmjs.org/lodash.isobject/-/lodash.isobject-3.0.2.tgz", @@ -22500,6 +22994,12 @@ "extend-shallow": "^3.0.0" } }, + "sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==", + "dev": true + }, "sshpk": { "version": "1.16.1", "resolved": "https://registry.npmjs.org/sshpk/-/sshpk-1.16.1.tgz", @@ -22686,6 +23186,12 @@ "safe-buffer": "~5.1.0" } }, + "string-argv": { + "version": "0.3.1", + "resolved": "https://registry.npmjs.org/string-argv/-/string-argv-0.3.1.tgz", + "integrity": "sha512-a1uQGz7IyVy9YwhqjZIZu1c8JO8dNIe20xBmSS6qu9kv++k3JGzCVmprbNN5Kn+BgzD5E7YYwg1CcjuJMRNsvg==", + "dev": true + }, "string-width": { "version": "4.2.3", "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", @@ -23340,6 +23846,12 @@ "builtins": "^1.0.3" } }, + "validator": { + "version": "13.7.0", + "resolved": "https://registry.npmjs.org/validator/-/validator-13.7.0.tgz", + "integrity": "sha512-nYXQLCBkpJ8X6ltALua9dRrZDHVYxjJ1wgskNt1lH9fzGjs3tgojGSCBjmEPwkWS1y29+DrizMTW19Pr9uB2nw==", + "dev": true + }, "value-or-function": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/value-or-function/-/value-or-function-3.0.0.tgz", @@ -24009,6 +24521,27 @@ "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==", "dev": true }, + "z-schema": { + "version": "5.0.3", + "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.3.tgz", + "integrity": "sha512-sGvEcBOTNum68x9jCpCVGPFJ6mWnkD0YxOcddDlJHRx3tKdB2q8pCHExMVZo/AV/6geuVJXG7hljDaWG8+5GDw==", + "dev": true, + "requires": { + "commander": "^2.20.3", + "lodash.get": "^4.4.2", + "lodash.isequal": "^4.5.0", + "validator": "^13.7.0" + }, + "dependencies": { + "commander": { + "version": "2.20.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", + "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", + "dev": true, + "optional": true + } + } + }, "zip-stream": { "version": "4.1.0", "resolved": "https://registry.npmjs.org/zip-stream/-/zip-stream-4.1.0.tgz", diff --git a/package.json b/package.json index 48f681c1a..b4acd5d00 100644 --- a/package.json +++ b/package.json @@ -70,6 +70,7 @@ "@blockly/dev-tools": "^4.0.2", "@blockly/theme-modern": "^2.1.1", "@hyperjump/json-schema": "^0.18.4", + "@microsoft/api-extractor": "^7.29.5", "@typescript-eslint/eslint-plugin": "^5.33.1", "@wdio/selenium-standalone-service": "^7.10.1", "chai": "^4.2.0", diff --git a/tsconfig.json b/tsconfig.json index 9dbdfcfab..a414b74e8 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -13,6 +13,8 @@ // Generate d.ts files and sourcemaps. "declaration": true, + // Generate declaration maps used for api-extractor + "declarationMap": true, "sourceMap": true, "module": "ES2015", diff --git a/tsdoc.json b/tsdoc.json new file mode 100644 index 000000000..92bab4192 --- /dev/null +++ b/tsdoc.json @@ -0,0 +1,40 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + // Include the definitions that are required for API Extractor + "extends": ["@microsoft/api-extractor/extends/tsdoc-base.json"], + "tagDefinitions": [ + { + "tagName": "@alias", + "syntaxKind": "block" + }, + { + "tagName": "@define", + "syntaxKind": "block" + }, + { + "tagName": "@license", + "syntaxKind": "block" + }, + { + "tagName": "@nocollapse", + "syntaxKind": "modifier" + }, + { + "tagName": "@suppress", + "syntaxKind": "block" + }, + { + "tagName": "@unrestricted", + "syntaxKind": "modifier" + } + ], + + "supportForTags": { + "@alias": true, + "@define": true, + "@license": true, + "@nocollapse": true, + "@suppress": true, + "@unrestricted": true + } +} \ No newline at end of file diff --git a/typings/blocks.d.ts b/typings/blocks.d.ts index b0b4af324..a611ec237 100644 --- a/typings/blocks.d.ts +++ b/typings/blocks.d.ts @@ -4,11 +4,6 @@ * SPDX-License-Identifier: Apache-2.0 */ -/** - * @fileoverview Type definitions for Blockly Blocks. - * @author samelh@google.com (Sam El-Husseini) - */ - export const colour: any; export const lists: any; export const logic: any; diff --git a/typings/core.d.ts b/typings/core.d.ts index 2cd6a07ef..f57e72f4f 100644 --- a/typings/core.d.ts +++ b/typings/core.d.ts @@ -4,9 +4,4 @@ * SPDX-License-Identifier: Apache-2.0 */ -/** - * @fileoverview Type definitions for Blockly core. - * @author samelh@google.com (Sam El-Husseini) - */ - export * from './core/blockly'; diff --git a/typings/dart.d.ts b/typings/dart.d.ts index 84c04d70f..f8ec31e4e 100644 --- a/typings/dart.d.ts +++ b/typings/dart.d.ts @@ -4,10 +4,5 @@ * SPDX-License-Identifier: Apache-2.0 */ -/** - * @fileoverview Type definitions for the Dart generator. - * @author samelh@google.com (Sam El-Husseini) - */ - declare const dart: any; export = dart; diff --git a/typings/index.d.ts b/typings/index.d.ts index ac3c88dde..70b7e79cc 100644 --- a/typings/index.d.ts +++ b/typings/index.d.ts @@ -4,11 +4,7 @@ * SPDX-License-Identifier: Apache-2.0 */ -/** - * @fileoverview Type definitions for Blockly. - * @author samelh@google.com (Sam El-Husseini) - */ - +import * as libraryBlocks from './blocks'; // Handcrafted file. export * from './core/blockly'; -export * as libraryBlocks from './blocks'; // Handcrafted file. +export {libraryBlocks}; export const JavaScript: any; diff --git a/typings/javascript.d.ts b/typings/javascript.d.ts index 998c7de1b..65061b62e 100644 --- a/typings/javascript.d.ts +++ b/typings/javascript.d.ts @@ -4,10 +4,5 @@ * SPDX-License-Identifier: Apache-2.0 */ -/** - * @fileoverview Type definitions for the JavaScript generator. - * @author samelh@google.com (Sam El-Husseini) - */ - declare const javascript: any; export = javascript; diff --git a/typings/lua.d.ts b/typings/lua.d.ts index e9898a9e2..7e3adc125 100644 --- a/typings/lua.d.ts +++ b/typings/lua.d.ts @@ -4,10 +4,5 @@ * SPDX-License-Identifier: Apache-2.0 */ -/** - * @fileoverview Type definitions for the Lua generator. - * @author samelh@google.com (Sam El-Husseini) - */ - declare const lua: any; export = lua; diff --git a/typings/php.d.ts b/typings/php.d.ts index d7c7a2b08..03ed95c4e 100644 --- a/typings/php.d.ts +++ b/typings/php.d.ts @@ -4,10 +4,5 @@ * SPDX-License-Identifier: Apache-2.0 */ -/** - * @fileoverview Type definitions for the PHP generator. - * @author samelh@google.com (Sam El-Husseini) - */ - declare const php: any; export = php; diff --git a/typings/python.d.ts b/typings/python.d.ts index 43a73b019..94a3ffdbb 100644 --- a/typings/python.d.ts +++ b/typings/python.d.ts @@ -4,10 +4,5 @@ * SPDX-License-Identifier: Apache-2.0 */ -/** - * @fileoverview Type definitions for the Python generator. - * @author samelh@google.com (Sam El-Husseini) - */ - declare const python: any; export = python;