CodingPirates/blockly
1
0
Fork 0
mirror of https://github.com/google/blockly.git synced 2026-01-06 00:20:37 +01:00
Code Issues Packages Projects Releases Wiki Activity

chore: Lint TsDoc. (#6353)

Browse Source 
* chore: add linting for tsdoc

* chore: don't require types on return

* chore: remove redundant fileoverview from ts

* chore: change return to returns and add some newlines

* chore: remove license tag

* chore: don't require params/return docs

* chore: remove spurious struct tags

* Revert "chore: change return to returns and add some newlines"

This reverts commit d6d8656a45.

* chore: don't auto-add param names

* chore: disable require-param bc it breaks on this

* return to returns and add line breaks

* chore: configure additional jsdoc rules

* chore: run format

* Revert "chore: remove license tag"

This reverts commit 173455588a.

* chore: allow license tag format

* chore: only require jsdoc on exported items

* chore: add missing jsdoc or silence where needed

* chore: run format

* chore: lint fixes
This commit is contained in:
Maribeth Bottorff
2022-08-23 14:27:22 -07:00
committed by GitHub
parent bb37d1b7aa
commit 037eb59b89
261 changed files with 3876 additions and 2341 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
core/extensions.ts
View File

@@ -4,18 +4,12 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Extensions are functions that help initialize blocks, usually
* adding dynamic behavior such as onchange handlers and mutators. These
* are applied using Block.applyExtension(), or the JSON "extensions"
* array attribute.
*/
/**
* Extensions are functions that help initialize blocks, usually
* adding dynamic behavior such as onchange handlers and mutators. These
* are applied using Block.applyExtension(), or the JSON "extensions"
* array attribute.
*
* @namespace Blockly.Extensions
*/
import * as goog from '../closure/goog/goog.js';
@@ -40,6 +34,7 @@ export const TEST_ONLY = {allExtensions};
* initialize blocks, usually adding dynamic behavior such as onchange
* handlers and mutators. These are applied using Block.applyExtension(), or
* the JSON "extensions" array attribute.
*
* @param name The name of this extension.
* @param initFn The function to initialize an extended block.
* @throws {Error} if the extension name is empty, the extension is already
@@ -61,6 +56,7 @@ export function register(name: string, initFn: Function) {
/**
* Registers a new extension function that adds all key/value of mixinObj.
*
* @param name The name of this extension.
* @param mixinObj The values to mix in.
* @throws {Error} if the extension name is empty or the extension is already
@@ -81,6 +77,7 @@ export function registerMixin(name: string, mixinObj: AnyDuringMigration) {
* At register time this performs some basic sanity checks on the mutator.
* The wrapper may also add a mutator dialog to the block, if both compose and
* decompose are defined on the mixin.
*
* @param name The name of this mutator extension.
* @param mixinObj The values to mix in.
* @param opt_helperFn An optional function to apply after mixing in the object.
@@ -117,6 +114,7 @@ export function registerMutator(
/**
* Unregisters the extension registered with the given name.
*
* @param name The name of the extension to unregister.
* @alias Blockly.Extensions.unregister
*/
@@ -131,8 +129,9 @@ export function unregister(name: string) {
/**
* Returns whether an extension is registered with the given name.
*
* @param name The name of the extension to check for.
* @return True if the extension is registered. False if it is not registered.
* @returns True if the extension is registered. False if it is not registered.
* @alias Blockly.Extensions.isRegistered
*/
export function isRegistered(name: string): boolean {
@@ -142,6 +141,7 @@ export function isRegistered(name: string): boolean {
/**
* Applies an extension method to a block. This should only be called during
* block construction.
*
* @param name The name of the extension.
* @param block The block to apply the named extension to.
* @param isMutator True if this extension defines a mutator.
@@ -181,6 +181,7 @@ export function apply(name: string, block: Block, isMutator: boolean) {
* Check that the given block does not have any of the four mutator properties
* defined on it. This function should be called before applying a mutator
* extension to a block, to make sure we are not overwriting properties.
*
* @param mutationName The name of the mutation to reference in error messages.
* @param block The block to check.
* @throws {Error} if any of the properties already exist on the block.
@@ -198,9 +199,10 @@ function checkNoMutatorProperties(mutationName: string, block: Block) {
/**
* Checks if the given object has both the 'mutationToDom' and 'domToMutation'
* functions.
*
* @param object The object to check.
* @param errorPrefix The string to prepend to any error message.
* @return True if the object has both functions. False if it has neither
* @returns True if the object has both functions. False if it has neither
* function.
* @throws {Error} if the object has only one of the functions, or either is not
* actually a function.
@@ -214,9 +216,10 @@ function checkXmlHooks(
/**
* Checks if the given object has both the 'saveExtraState' and 'loadExtraState'
* functions.
*
* @param object The object to check.
* @param errorPrefix The string to prepend to any error message.
* @return True if the object has both functions. False if it has neither
* @returns True if the object has both functions. False if it has neither
* function.
* @throws {Error} if the object has only one of the functions, or either is not
* actually a function.
@@ -230,9 +233,10 @@ function checkJsonHooks(
/**
* Checks if the given object has both the 'compose' and 'decompose' functions.
*
* @param object The object to check.
* @param errorPrefix The string to prepend to any error message.
* @return True if the object has both functions. False if it has neither
* @returns True if the object has both functions. False if it has neither
* function.
* @throws {Error} if the object has only one of the functions, or either is not
* actually a function.
@@ -246,10 +250,11 @@ function checkMutatorDialog(
/**
* Checks that both or neither of the given functions exist and that they are
* indeed functions.
*
* @param func1 The first function in the pair.
* @param func2 The second function in the pair.
* @param errorPrefix The string to prepend to any error message.
* @return True if the object has both functions. False if it has neither
* @returns True if the object has both functions. False if it has neither
* function.
* @throws {Error} If the object has only one of the functions, or either is not
* actually a function.
@@ -270,6 +275,7 @@ function checkHasFunctionPair(
/**
* Checks that the given object required mutator properties.
*
* @param errorPrefix The string to prepend to any error message.
* @param object The object to inspect.
*/
@@ -289,9 +295,10 @@ function checkHasMutatorProperties(
/**
* Get a list of values of mutator properties on the given block.
*
* @param block The block to inspect.
* @return A list with all of the defined properties, which should be functions,
* but may be anything other than undefined.
* @returns A list with all of the defined properties, which should be
* functions, but may be anything other than undefined.
*/
function getMutatorProperties(block: Block): AnyDuringMigration[] {
const result = [];
@@ -322,9 +329,10 @@ function getMutatorProperties(block: Block): AnyDuringMigration[] {
* Check that the current mutator properties match a list of old mutator
* properties. This should be called after applying a non-mutator extension,
* to verify that the extension didn't change properties it shouldn't.
*
* @param oldProperties The old values to compare to.
* @param block The block to inspect for new values.
* @return True if the property lists match.
* @returns True if the property lists match.
*/
function mutatorPropertiesMatch(
oldProperties: AnyDuringMigration[], block: Block): boolean {
@@ -342,6 +350,7 @@ function mutatorPropertiesMatch(
/**
* Calls a function after the page has loaded, possibly immediately.
*
* @param fn Function to run.
* @throws Error Will throw if no global document can be found (e.g., Node.js).
* @internal
@@ -376,10 +385,11 @@ export function runAfterPageLoad(fn: () => AnyDuringMigration) {
* loading the first block of any given type, the extension will validate every
* dropdown option has a matching tooltip in the lookupTable. Errors are
* reported as warnings in the console, and are never fatal.
*
* @param dropdownName The name of the field whose value is the key to the
* lookup table.
* @param lookupTable The table of field values to tooltip text.
* @return The extension function.
* @returns The extension function.
* @alias Blockly.Extensions.buildTooltipForDropdown
*/
export function buildTooltipForDropdown(
@@ -432,6 +442,7 @@ export function buildTooltipForDropdown(
/**
* Checks all options keys are present in the provided string lookup table.
* Emits console warnings when they are not.
*
* @param block The block containing the dropdown
* @param dropdownName The name of the dropdown
* @param lookupTable The string lookup table
@@ -457,10 +468,11 @@ function checkDropdownOptionsInTable(
* Builds an extension function that will install a dynamic tooltip. The
* tooltip message should include the string '%1' and that string will be
* replaced with the text of the named field.
*
* @param msgTemplate The template form to of the message text, with %1
* placeholder.
* @param fieldName The field with the replacement text.
* @return The extension function.
* @returns The extension function.
* @alias Blockly.Extensions.buildTooltipWithFieldText
*/
export function buildTooltipWithFieldText(