CodingPirates/blockly
1
0
Fork 0
mirror of https://github.com/google/blockly.git synced 2026-01-07 09:00:11 +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

47
core/variables.ts
View File

@@ -4,12 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Utility functions for handling variables.
*/
/**
* Utility functions for handling variables.
*
* @namespace Blockly.Variables
*/
import * as goog from '../closure/goog/goog.js';
@@ -31,6 +28,7 @@ import * as Xml from './xml.js';
* variable blocks.
* See also Blockly.Procedures.CATEGORY_NAME and
* Blockly.VariablesDynamic.CATEGORY_NAME.
*
* @alias Blockly.Variables.CATEGORY_NAME
*/
export const CATEGORY_NAME = 'VARIABLE';
@@ -40,8 +38,9 @@ export const CATEGORY_NAME = 'VARIABLE';
* For use by generators.
* To get a list of all variables on a workspace, including unused variables,
* call Workspace.getAllVariables.
*
* @param ws The workspace to search for variables.
* @return Array of variable models.
* @returns Array of variable models.
* @alias Blockly.Variables.allUsedVarModels
*/
export function allUsedVarModels(ws: Workspace): VariableModel[] {
@@ -73,8 +72,9 @@ const ALL_DEVELOPER_VARS_WARNINGS_BY_BLOCK_TYPE: {[key: string]: boolean} = {};
* To declare developer variables, define the getDeveloperVariables function on
* your block and return a list of variable names.
* For use by generators.
*
* @param workspace The workspace to search.
* @return A list of non-duplicated variable names.
* @returns A list of non-duplicated variable names.
* @alias Blockly.Variables.allDeveloperVariables
*/
export function allDeveloperVariables(workspace: Workspace): string[] {
@@ -108,8 +108,9 @@ export function allDeveloperVariables(workspace: Workspace): string[] {
/**
* Construct the elements (blocks and button) required by the flyout for the
* variable category.
*
* @param workspace The workspace containing variables.
* @return Array of XML elements.
* @returns Array of XML elements.
* @alias Blockly.Variables.flyoutCategory
*/
export function flyoutCategory(workspace: WorkspaceSvg): Element[] {
@@ -136,8 +137,9 @@ export function flyoutCategory(workspace: WorkspaceSvg): Element[] {
/**
* Construct the blocks required by the flyout for the variable category.
*
* @param workspace The workspace containing variables.
* @return Array of XML block elements.
* @returns Array of XML block elements.
* @alias Blockly.Variables.flyoutCategoryBlocks
*/
export function flyoutCategoryBlocks(workspace: Workspace): Element[] {
@@ -208,8 +210,9 @@ export const VAR_LETTER_OPTIONS = 'ijkmnopqrstuvwxyzabcdefgh';
* generate single letter variable names in the range 'i' to 'z' to start with.
* If no unique name is located it will try 'i' to 'z', 'a' to 'h',
* then 'i2' to 'z2' etc. Skip 'l'.
*
* @param workspace The workspace to be unique in.
* @return New variable name.
* @returns New variable name.
* @alias Blockly.Variables.generateUniqueName
*/
export function generateUniqueName(workspace: Workspace): string {
@@ -228,9 +231,10 @@ 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 start with the character passed to startChar.
*
* @param startChar The character to start the search at.
* @param usedNames A list of all of the used names.
* @return A unique name that is not present in the usedNames array.
* @returns A unique name that is not present in the usedNames array.
* @alias Blockly.Variables.generateUniqueNameFromOptions
*/
export function generateUniqueNameFromOptions(
@@ -329,6 +333,7 @@ export function createVariableButtonHandler(
* Opens a prompt that allows the user to enter a new name for a variable.
* Triggers a rename if the new name is valid. Or re-prompts if there is a
* collision.
*
* @param workspace The workspace on which to rename the variable.
* @param variable Variable to rename.
* @param opt_callback A callback. It will be passed an acceptable new variable
@@ -373,6 +378,7 @@ export function renameVariable(
/**
* Prompt the user for a new variable name.
*
* @param promptText The string of the prompt.
* @param defaultText The default value to show in the prompt's field.
* @param callback A callback. It will return the new variable name, or null if
@@ -398,10 +404,11 @@ export function promptName(
/**
* Check whether there exists a variable with the given name but a different
* type.
*
* @param name The name to search for.
* @param type The type to exclude from the search.
* @param workspace The workspace to search for the variable.
* @return The variable with the given name and a different type, or null if
* @returns The variable with the given name and a different type, or null if
* none was found.
*/
function nameUsedWithOtherType(
@@ -419,9 +426,10 @@ function nameUsedWithOtherType(
/**
* Check whether there exists a variable with the given name of any type.
*
* @param name The name to search for.
* @param workspace The workspace to search for the variable.
* @return The variable with the given name, or null if none was found.
* @returns The variable with the given name, or null if none was found.
* @alias Blockly.Variables.nameUsedWithAnyType
*/
export function nameUsedWithAnyType(
@@ -439,8 +447,9 @@ export function nameUsedWithAnyType(
/**
* Generate DOM objects representing a variable field.
*
* @param variableModel The variable model to represent.
* @return The generated DOM.
* @returns The generated DOM.
* @alias Blockly.Variables.generateVariableFieldDom
*/
export function generateVariableFieldDom(variableModel: VariableModel): Element|
@@ -460,12 +469,13 @@ export function generateVariableFieldDom(variableModel: VariableModel): Element|
/**
* Helper function to look up or create a variable on the given workspace.
* If no variable exists, creates and returns it.
*
* @param workspace The workspace to search for the variable. It may be a
* flyout workspace or main workspace.
* @param id The ID to use to look up or create the variable, or null.
* @param opt_name The string to use to look up or create the variable.
* @param opt_type The type to use to look up or create the variable.
* @return The variable corresponding to the given ID or name + type
* @returns The variable corresponding to the given ID or name + type
* combination.
* @alias Blockly.Variables.getOrCreateVariablePackage
*/
@@ -483,6 +493,7 @@ export function getOrCreateVariablePackage(
* Look up a variable on the given workspace.
* Always looks in the main workspace before looking in the flyout workspace.
* Always prefers lookup by ID to lookup by name + type.
*
* @param workspace The workspace to search for the variable. It may be a
* flyout workspace or main workspace.
* @param id The ID to use to look up the variable, or null.
@@ -490,7 +501,7 @@ export function getOrCreateVariablePackage(
* Only used if lookup by ID fails.
* @param opt_type The type to use to look up the variable.
* Only used if lookup by ID fails.
* @return The variable corresponding to the given ID or name + type
* @returns The variable corresponding to the given ID or name + type
* combination, or null if not found.
* @alias Blockly.Variables.getVariable
*/
@@ -527,12 +538,13 @@ export function getVariable(
/**
* Helper function to create a variable on the given workspace.
*
* @param workspace The workspace in which to create the variable. It may be a
* flyout workspace or main workspace.
* @param id The ID to use to create the variable, or null.
* @param opt_name The string to use to create the variable.
* @param opt_type The type to use to create the variable.
* @return The variable corresponding to the given ID or name + type
* @returns The variable corresponding to the given ID or name + type
* combination.
*/
function createVariable(
@@ -565,10 +577,11 @@ function createVariable(
* Helper function to get the list of variables that have been added to the
* workspace after adding a new block, using the given list of variables that
* were in the workspace before the new block was added.
*
* @param workspace The workspace to inspect.
* @param originalVariables The array of variables that existed in the workspace
* before adding the new block.
* @return The new array of variables that were freshly added to the workspace
* @returns The new array of variables that were freshly added to the workspace
* after creating the new block, or [] if no new variables were added to the
* workspace.
* @alias Blockly.Variables.getAddedVariables