From 5333451defd45bc39c719b262b171abd865bcda6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Sun, 9 Jan 2022 15:56:07 +0100 Subject: [PATCH] Got rid of the last brace-typed and hyphen-less params etc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .changeset/pink-suns-walk.md | 25 ++++++++++++ .../backend-common/src/database/config.ts | 4 +- .../connectors/defaultNameOverride.ts | 2 +- .../connectors/defaultSchemaOverride.ts | 2 +- .../src/database/connectors/mysql.ts | 18 ++++----- .../src/database/connectors/postgres.ts | 22 +++++------ .../src/database/connectors/sqlite3.ts | 8 ++-- .../backend-common/src/service/lib/config.ts | 8 ++-- .../src/service/lib/hostFactory.ts | 10 ++--- packages/core-components/api-report.md | 15 -------- .../components/CodeSnippet/CodeSnippet.tsx | 2 +- .../FeatureDiscovery/lib/usePortal.ts | 2 +- .../components/WarningPanel/WarningPanel.tsx | 18 +++++---- .../src/layout/ItemCard/ItemCard.tsx | 8 ++-- packages/create-app/src/lib/tasks.ts | 18 ++++----- packages/e2e-test/src/lib/helpers.ts | 2 +- packages/integration/api-report.md | 5 --- packages/integration/src/gitlab/config.ts | 8 ++-- packages/techdocs-common/api-report.md | 10 ----- .../src/stages/generate/helpers.ts | 26 ++++++------- .../src/stages/prepare/types.ts | 11 +++--- .../src/stages/publish/helpers.ts | 4 +- .../src/stages/publish/types.ts | 4 +- .../src/api/ApacheAirflowClient.ts | 4 +- plugins/auth-backend/api-report.md | 38 +------------------ plugins/auth-backend/src/lib/oauth/types.ts | 11 ++---- .../src/providers/github/provider.ts | 2 +- plugins/auth-backend/src/providers/types.ts | 20 ++-------- .../components/PullRequestsPage/lib/utils.ts | 10 ++--- plugins/catalog-backend/api-report.md | 38 ------------------- plugins/catalog-backend/src/catalog/types.ts | 7 +--- .../src/ingestion/processors/github/github.ts | 24 ++++++------ .../catalog-backend/src/ingestion/types.ts | 2 +- .../src/legacy/database/search.ts | 4 +- .../src/legacy/database/types.ts | 20 +++++----- .../legacy/ingestion/HigherOrderOperations.ts | 2 +- .../src/legacy/ingestion/types.ts | 2 +- .../src/legacy/service/CatalogBuilder.ts | 16 ++++---- .../src/processing/TaskPipeline.ts | 2 +- .../catalog-backend/src/processing/refresh.ts | 2 +- .../src/service/NextCatalogBuilder.ts | 18 ++++----- .../src/stitching/buildEntitySearch.ts | 4 +- .../src/util/runPeriodically.ts | 4 +- plugins/catalog-backend/src/util/timing.ts | 2 +- plugins/catalog-import/api-report.md | 8 ---- .../src/components/ImportStepper/defaults.tsx | 4 +- .../StepInitAnalyzeUrl/StepInitAnalyzeUrl.tsx | 6 +-- .../PreparePullRequestForm.tsx | 6 +-- .../StepPrepareSelectLocations.tsx | 8 ++-- .../src/components/useImportState.ts | 2 +- plugins/catalog-react/api-report.md | 12 ------ .../FavoriteEntity/FavoriteEntity.tsx | 2 +- plugins/catalog-react/src/types.ts | 9 ++--- .../src/service/converter/cobertura.ts | 8 ++-- .../src/service/converter/jacoco.ts | 4 +- .../components/FileExplorer/Highlighter.ts | 4 +- plugins/cost-insights/api-report.md | 12 ------ .../cost-insights/src/api/CostInsightsApi.ts | 18 ++++----- plugins/cost-insights/src/utils/duration.ts | 4 +- plugins/fossa/src/api/FossaApi.ts | 4 +- plugins/jenkins/api-report.md | 5 --- plugins/jenkins/src/api/JenkinsApi.ts | 8 +--- .../src/components/useBuildWithSteps.ts | 4 +- plugins/scaffolder-backend/api-report.md | 1 - .../actions/builtin/github/OctokitProvider.ts | 2 +- plugins/scaffolder/api-report.md | 5 --- plugins/scaffolder/src/api.ts | 8 ++-- .../FavouriteTemplate/FavouriteTemplate.tsx | 2 +- .../src/runPeriodically.ts | 4 +- .../techdocs-backend/src/service/router.ts | 4 +- plugins/techdocs/api-report.md | 26 ------------- plugins/techdocs/src/client.ts | 26 ++++++------- 72 files changed, 247 insertions(+), 423 deletions(-) create mode 100644 .changeset/pink-suns-walk.md diff --git a/.changeset/pink-suns-walk.md b/.changeset/pink-suns-walk.md new file mode 100644 index 0000000000..1857b90811 --- /dev/null +++ b/.changeset/pink-suns-walk.md @@ -0,0 +1,25 @@ +--- +'@backstage/backend-common': patch +'@backstage/core-components': patch +'@backstage/create-app': patch +'@backstage/integration': patch +'@backstage/techdocs-common': patch +'@backstage/plugin-apache-airflow': patch +'@backstage/plugin-auth-backend': patch +'@backstage/plugin-azure-devops': patch +'@backstage/plugin-catalog-backend': patch +'@backstage/plugin-catalog-import': patch +'@backstage/plugin-catalog-react': patch +'@backstage/plugin-code-coverage': patch +'@backstage/plugin-code-coverage-backend': patch +'@backstage/plugin-cost-insights': patch +'@backstage/plugin-fossa': patch +'@backstage/plugin-jenkins': patch +'@backstage/plugin-scaffolder': patch +'@backstage/plugin-scaffolder-backend': patch +'@backstage/plugin-search-backend-node': patch +'@backstage/plugin-techdocs': patch +'@backstage/plugin-techdocs-backend': patch +--- + +Cleaned up API exports diff --git a/packages/backend-common/src/database/config.ts b/packages/backend-common/src/database/config.ts index cf821087d7..64ca05a06f 100644 --- a/packages/backend-common/src/database/config.ts +++ b/packages/backend-common/src/database/config.ts @@ -20,8 +20,8 @@ import { merge } from 'lodash'; * Merges database objects together * * @public - * @param config The base config. The input is not modified - * @param overrides Any additional overrides + * @param config - The base config. The input is not modified + * @param overrides - Any additional overrides */ export function mergeDatabaseConfig(config: any, ...overrides: any[]) { return merge({}, config, ...overrides); diff --git a/packages/backend-common/src/database/connectors/defaultNameOverride.ts b/packages/backend-common/src/database/connectors/defaultNameOverride.ts index d48cedd0ff..bc467eb7f6 100644 --- a/packages/backend-common/src/database/connectors/defaultNameOverride.ts +++ b/packages/backend-common/src/database/connectors/defaultNameOverride.ts @@ -21,7 +21,7 @@ import { Knex } from 'knex'; * Default override for knex database drivers which accept ConnectionConfig * with `connection.database` as the database name field. * - * @param name database name to get config override for + * @param name - database name to get config override for */ export default function defaultNameOverride( name: string, diff --git a/packages/backend-common/src/database/connectors/defaultSchemaOverride.ts b/packages/backend-common/src/database/connectors/defaultSchemaOverride.ts index 62ad8ab8c8..4e76308542 100644 --- a/packages/backend-common/src/database/connectors/defaultSchemaOverride.ts +++ b/packages/backend-common/src/database/connectors/defaultSchemaOverride.ts @@ -18,7 +18,7 @@ import { Knex } from 'knex'; /** * Provides a partial knex config with schema name override. * - * @param name schema name to get config override for + * @param name - schema name to get config override for */ export default function defaultSchemaOverride( name: string, diff --git a/packages/backend-common/src/database/connectors/mysql.ts b/packages/backend-common/src/database/connectors/mysql.ts index 94dce508c7..b75dc3d99c 100644 --- a/packages/backend-common/src/database/connectors/mysql.ts +++ b/packages/backend-common/src/database/connectors/mysql.ts @@ -26,8 +26,8 @@ import defaultNameOverride from './defaultNameOverride'; /** * Creates a knex mysql database connection * - * @param dbConfig The database config - * @param overrides Additional options to merge with the config + * @param dbConfig - The database config + * @param overrides - Additional options to merge with the config */ export function createMysqlDatabaseClient( dbConfig: Config, @@ -41,8 +41,8 @@ export function createMysqlDatabaseClient( /** * Builds a knex mysql database connection * - * @param dbConfig The database config - * @param overrides Additional options to merge with the config + * @param dbConfig - The database config + * @param overrides - Additional options to merge with the config */ export function buildMysqlDatabaseConfig( dbConfig: Config, @@ -61,8 +61,8 @@ export function buildMysqlDatabaseConfig( /** * Gets the mysql connection config * - * @param dbConfig The database config - * @param parseConnectionString Flag to explicitly control connection string parsing + * @param dbConfig - The database config + * @param parseConnectionString - Flag to explicitly control connection string parsing */ export function getMysqlConnectionConfig( dbConfig: Config, @@ -86,7 +86,7 @@ export function getMysqlConnectionConfig( * Parses a mysql connection string. * * e.g. mysql://examplename:somepassword@examplehost:3306/dbname - * @param connectionString The mysql connection string + * @param connectionString - The mysql connection string */ export function parseMysqlConnectionString( connectionString: string, @@ -140,8 +140,8 @@ export function parseMysqlConnectionString( /** * Creates the missing mysql database if it does not exist * - * @param dbConfig The database config - * @param databases The names of the databases to create + * @param dbConfig - The database config + * @param databases - The names of the databases to create */ export async function ensureMysqlDatabaseExists( dbConfig: Config, diff --git a/packages/backend-common/src/database/connectors/postgres.ts b/packages/backend-common/src/database/connectors/postgres.ts index 823d50f73f..c780fb829b 100644 --- a/packages/backend-common/src/database/connectors/postgres.ts +++ b/packages/backend-common/src/database/connectors/postgres.ts @@ -26,8 +26,8 @@ import defaultSchemaOverride from './defaultSchemaOverride'; /** * Creates a knex postgres database connection * - * @param dbConfig The database config - * @param overrides Additional options to merge with the config + * @param dbConfig - The database config + * @param overrides - Additional options to merge with the config */ export function createPgDatabaseClient( dbConfig: Config, @@ -41,8 +41,8 @@ export function createPgDatabaseClient( /** * Builds a knex postgres database connection * - * @param dbConfig The database config - * @param overrides Additional options to merge with the config + * @param dbConfig - The database config + * @param overrides - Additional options to merge with the config */ export function buildPgDatabaseConfig( dbConfig: Config, @@ -61,8 +61,8 @@ export function buildPgDatabaseConfig( /** * Gets the postgres connection config * - * @param dbConfig The database config - * @param parseConnectionString Flag to explicitly control connection string parsing + * @param dbConfig - The database config + * @param parseConnectionString - Flag to explicitly control connection string parsing */ export function getPgConnectionConfig( dbConfig: Config, @@ -85,7 +85,7 @@ export function getPgConnectionConfig( /** * Parses a connection string using pg-connection-string * - * @param connectionString The postgres connection string + * @param connectionString - The postgres connection string */ export function parsePgConnectionString(connectionString: string) { const parse = requirePgConnectionString(); @@ -103,8 +103,8 @@ function requirePgConnectionString() { /** * Creates the missing Postgres database if it does not exist * - * @param dbConfig The database config - * @param databases The name of the databases to create + * @param dbConfig - The database config + * @param databases - The name of the databases to create */ export async function ensurePgDatabaseExists( dbConfig: Config, @@ -139,8 +139,8 @@ export async function ensurePgDatabaseExists( /** * Creates the missing Postgres schema if it does not exist * - * @param dbConfig The database config - * @param schemas The name of the schemas to create + * @param dbConfig - The database config + * @param schemas - The name of the schemas to create */ export async function ensurePgSchemaExists( dbConfig: Config, diff --git a/packages/backend-common/src/database/connectors/sqlite3.ts b/packages/backend-common/src/database/connectors/sqlite3.ts index 41f80ed293..8e47720f82 100644 --- a/packages/backend-common/src/database/connectors/sqlite3.ts +++ b/packages/backend-common/src/database/connectors/sqlite3.ts @@ -25,8 +25,8 @@ import { DatabaseConnector } from '../types'; /** * Creates a knex SQLite3 database connection * - * @param dbConfig The database config - * @param overrides Additional options to merge with the config + * @param dbConfig - The database config + * @param overrides - Additional options to merge with the config */ export function createSqliteDatabaseClient( dbConfig: Config, @@ -58,8 +58,8 @@ export function createSqliteDatabaseClient( /** * Builds a knex SQLite3 connection config * - * @param dbConfig The database config - * @param overrides Additional options to merge with the config + * @param dbConfig - The database config + * @param overrides - Additional options to merge with the config */ export function buildSqliteDatabaseConfig( dbConfig: Config, diff --git a/packages/backend-common/src/service/lib/config.ts b/packages/backend-common/src/service/lib/config.ts index 91eeff13aa..93cc12b7d4 100644 --- a/packages/backend-common/src/service/lib/config.ts +++ b/packages/backend-common/src/service/lib/config.ts @@ -55,7 +55,7 @@ type CustomOrigin = ( /** * Reads some base options out of a config object. * - * @param config The root of a backend config object + * @param config - The root of a backend config object * @returns A base options object * * @example @@ -98,7 +98,7 @@ export function readBaseOptions(config: Config): BaseOptions { /** * Attempts to read a CORS options object from the root of a config object. * - * @param config The root of a backend config object + * @param config - The root of a backend config object * @returns A CORS options object, or undefined if not specified * * @example @@ -132,7 +132,7 @@ export function readCorsOptions(config: Config): CorsOptions | undefined { /** * Attempts to read a CSP options object from the root of a config object. * - * @param config The root of a backend config object + * @param config - The root of a backend config object * @returns A CSP options object, or undefined if not specified. Values can be * false as well, which means to remove the default behavior for that * key. @@ -168,7 +168,7 @@ export function readCspOptions( /** * Attempts to read a https settings object from the root of a config object. * - * @param config The root of a backend config object + * @param config - The root of a backend config object * @returns A https settings object, or undefined if not specified * * @example diff --git a/packages/backend-common/src/service/lib/hostFactory.ts b/packages/backend-common/src/service/lib/hostFactory.ts index d3795893f7..572d8483b1 100644 --- a/packages/backend-common/src/service/lib/hostFactory.ts +++ b/packages/backend-common/src/service/lib/hostFactory.ts @@ -29,8 +29,8 @@ const IP_HOSTNAME_REGEX = /:|^\d+\.\d+\.\d+\.\d+$/; /** * Creates a Http server instance based on an Express application. * - * @param app The Express application object - * @param logger Optional Winston logger object + * @param app - The Express application object + * @param logger - Optional Winston logger object * @returns A Http server instance * */ @@ -46,9 +46,9 @@ export function createHttpServer( /** * Creates a Https server instance based on an Express application. * - * @param app The Express application object - * @param httpsSettings HttpsSettings for self-signed certificate generation - * @param logger Optional Winston logger object + * @param app - The Express application object + * @param httpsSettings - HttpsSettings for self-signed certificate generation + * @param logger - Optional Winston logger object * @returns A Https server instance * */ diff --git a/packages/core-components/api-report.md b/packages/core-components/api-report.md index e84982e31a..87a9186d5b 100644 --- a/packages/core-components/api-report.md +++ b/packages/core-components/api-report.md @@ -151,7 +151,6 @@ export function CodeSnippet(props: CodeSnippetProps): JSX.Element; export interface CodeSnippetProps { customStyle?: any; highlightedNumbers?: number[]; - // Warning: (tsdoc-reference-missing-identifier) Syntax error in declaration reference: expecting a member identifier language: string; showCopyCodeButton?: boolean; showLineNumbers?: boolean; @@ -527,8 +526,6 @@ export type InfoCardVariants = 'flex' | 'fullHeight' | 'gridItem'; // @public export function IntroCard(props: IntroCardProps): JSX.Element; -// Warning: (tsdoc-malformed-html-name) Invalid HTML element: Expecting an HTML name -// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag // Warning: (ae-forgotten-export) The symbol "ItemCardProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "ItemCard" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -2415,18 +2412,6 @@ export function useSupportConfig(): SupportConfig; // @public (undocumented) export function WarningIcon(props: IconComponentProps): JSX.Element; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-with-invalid-optional-name) The @param should not include a JSDoc-style optional name; it must not be enclosed in '[ ]' brackets. -// Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-with-invalid-optional-name) The @param should not include a JSDoc-style optional name; it must not be enclosed in '[ ]' brackets. -// Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-with-invalid-optional-name) The @param should not include a JSDoc-style optional name; it must not be enclosed in '[ ]' brackets. -// Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-with-invalid-optional-name) The @param should not include a JSDoc-style optional name; it must not be enclosed in '[ ]' brackets. -// Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' // Warning: (ae-forgotten-export) The symbol "WarningProps" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "WarningPanel" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // diff --git a/packages/core-components/src/components/CodeSnippet/CodeSnippet.tsx b/packages/core-components/src/components/CodeSnippet/CodeSnippet.tsx index ed78b2c590..0e4b12defc 100644 --- a/packages/core-components/src/components/CodeSnippet/CodeSnippet.tsx +++ b/packages/core-components/src/components/CodeSnippet/CodeSnippet.tsx @@ -33,7 +33,7 @@ export interface CodeSnippetProps { */ text: string; /** - * Language used by {@link .text} + * Language used by {@link CodeSnippetProps.text} */ language: string; /** diff --git a/packages/core-components/src/components/FeatureDiscovery/lib/usePortal.ts b/packages/core-components/src/components/FeatureDiscovery/lib/usePortal.ts index c1377b6060..f8972959f0 100644 --- a/packages/core-components/src/components/FeatureDiscovery/lib/usePortal.ts +++ b/packages/core-components/src/components/FeatureDiscovery/lib/usePortal.ts @@ -45,7 +45,7 @@ function addRootElement(rootElem: Element): void { * const target = usePortal(id, [id]); * return createPortal(children, target); * - * @param id The id of the target container, e.g 'modal' or 'spotlight' + * @param id - The id of the target container, e.g 'modal' or 'spotlight' * @returns The DOM node to use as the Portal target. */ export function usePortal(id: string): HTMLElement { diff --git a/packages/core-components/src/components/WarningPanel/WarningPanel.tsx b/packages/core-components/src/components/WarningPanel/WarningPanel.tsx index 0cf250497b..661bb1da22 100644 --- a/packages/core-components/src/components/WarningPanel/WarningPanel.tsx +++ b/packages/core-components/src/components/WarningPanel/WarningPanel.tsx @@ -134,14 +134,18 @@ const capitalize = (s: string) => { }; /** - * WarningPanel. Show a user friendly error message to a user similar to ErrorPanel except that the warning panel - * only shows the warning message to the user. + * WarningPanel. Show a user friendly error message to a user similar to + * ErrorPanel except that the warning panel only shows the warning message to + * the user. * - * @param {string} [severity=warning] Ability to change the severity of the alert. - * @param {string} [title] A title for the warning. If not supplied, "Warning" will be used. - * @param {Object} [message] Optional more detailed user-friendly message elaborating on the cause of the error. - * @param {Object} [children] Objects to provide context, such as a stack trace or detailed error reporting. - * Will be available inside an unfolded accordion. + * @param severity - Ability to change the severity of the alert. Default value + * "warning" + * @param title - A title for the warning. If not supplied, "Warning" will be + * used. + * @param message - Optional more detailed user-friendly message elaborating on + * the cause of the error. + * @param children - Objects to provide context, such as a stack trace or detailed + * error reporting. Will be available inside an unfolded accordion. */ export function WarningPanel(props: WarningProps) { const { diff --git a/packages/core-components/src/layout/ItemCard/ItemCard.tsx b/packages/core-components/src/layout/ItemCard/ItemCard.tsx index 82426c14e1..e2efd0c136 100644 --- a/packages/core-components/src/layout/ItemCard/ItemCard.tsx +++ b/packages/core-components/src/layout/ItemCard/ItemCard.tsx @@ -40,8 +40,7 @@ type ItemCardProps = { * This card type has been deprecated. Instead use plain MUI Card and helpers * where appropriate. * - * - * - * + * ``` * - * @deprecated Use plain MUI and composable helpers instead. + * @deprecated Use plain MUI `` and composable helpers instead. * @see https://material-ui.com/components/cards/ */ export function ItemCard(props: ItemCardProps) { diff --git a/packages/create-app/src/lib/tasks.ts b/packages/create-app/src/lib/tasks.ts index 2793088892..4bd7050fc2 100644 --- a/packages/create-app/src/lib/tasks.ts +++ b/packages/create-app/src/lib/tasks.ts @@ -167,8 +167,8 @@ export async function checkAppExistsTask(rootDir: string, name: string) { /** * Verify that application `path` exists, otherwise create the directory * - * @param {string} path - target to create directory - * @throws {Error} if `path` is a file, or `fs.mkdir` fails + * @param path - target to create directory + * @throws if `path` is a file, or `fs.mkdir` fails */ export async function checkPathExistsTask(path: string) { await Task.forItem('checking', path, async () => { @@ -184,8 +184,8 @@ export async function checkPathExistsTask(path: string) { /** * Create a folder to store templated files * - * @param {string} tempDir - target temporary directory - * @throws {Error} if `fs.mkdir` fails + * @param tempDir - target temporary directory + * @throws if `fs.mkdir` fails */ export async function createTemporaryAppFolderTask(tempDir: string) { await Task.forItem('creating', 'temporary directory', async () => { @@ -200,7 +200,7 @@ export async function createTemporaryAppFolderTask(tempDir: string) { /** * Run `yarn install` and `run tsc` in application directory * - * @param {string} appDir - location of application to build + * @param appDir - location of application to build */ export async function buildAppTask(appDir: string) { const runCmd = async (cmd: string) => { @@ -221,10 +221,10 @@ export async function buildAppTask(appDir: string) { /** * Move temporary directory to destination application folder * - * @param {string} tempDir source path to copy files from - * @param {string} destination target path to copy files - * @param {string} id - * @throws {Error} if `fs.move` fails + * @param tempDir - source path to copy files from + * @param destination - target path to copy files + * @param id - item ID + * @throws if `fs.move` fails */ export async function moveAppTask( tempDir: string, diff --git a/packages/e2e-test/src/lib/helpers.ts b/packages/e2e-test/src/lib/helpers.ts index 350898234d..ccedf52ade 100644 --- a/packages/e2e-test/src/lib/helpers.ts +++ b/packages/e2e-test/src/lib/helpers.ts @@ -90,7 +90,7 @@ export function exitWithError(err: Error & { code?: unknown }) { * Waits for fn() to be true * Checks every 100ms * .cancel() is available - * @returns {Promise} Promise of resolution + * @returns Promise of resolution */ export function waitFor(fn: () => boolean, maxSeconds: number = 120) { let count = 0; diff --git a/packages/integration/api-report.md b/packages/integration/api-report.md index 8e74470973..f1f83a5601 100644 --- a/packages/integration/api-report.md +++ b/packages/integration/api-report.md @@ -432,9 +432,4 @@ export class SingleInstanceGithubCredentialsProvider static create: (config: GitHubIntegrationConfig) => GithubCredentialsProvider; getCredentials(opts: { url: string }): Promise; } - -// Warnings were encountered during analysis: -// -// src/gitlab/config.d.ts:29:68 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// src/gitlab/config.d.ts:29:63 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" ``` diff --git a/packages/integration/src/gitlab/config.ts b/packages/integration/src/gitlab/config.ts index f9c15c3219..f74b849c74 100644 --- a/packages/integration/src/gitlab/config.ts +++ b/packages/integration/src/gitlab/config.ts @@ -28,13 +28,13 @@ const GITLAB_API_BASE_URL = 'https://gitlab.com/api/v4'; */ export type GitLabIntegrationConfig = { /** - * The host of the target that this matches on, e.g. "gitlab.com". + * The host of the target that this matches on, e.g. `gitlab.com`. */ host: string; /** * The base URL of the API of this provider, e.g. - * "https://gitlab.com/api/v4", with no trailing slash. + * `https://gitlab.com/api/v4`, with no trailing slash. * * May be omitted specifically for public GitLab; then it will be deduced. */ @@ -48,10 +48,10 @@ export type GitLabIntegrationConfig = { token?: string; /** - * The baseUrl of this provider, e.g. "https://gitlab.com", which is passed + * The baseUrl of this provider, e.g. `https://gitlab.com`, which is passed * into the GitLab client. * - * If no baseUrl is provided, it will default to https://${host} + * If no baseUrl is provided, it will default to `https://${host}` */ baseUrl: string; }; diff --git a/packages/techdocs-common/api-report.md b/packages/techdocs-common/api-report.md index 5c0a9f87f6..5cb2d81b1d 100644 --- a/packages/techdocs-common/api-report.md +++ b/packages/techdocs-common/api-report.md @@ -172,12 +172,6 @@ export interface PublisherBase { fetchTechDocsMetadata(entityName: EntityName): Promise; getReadiness(): Promise; hasDocsBeenGenerated(entityName: Entity): Promise; - // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag - // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag - // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" - // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" - // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag - // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" // Warning: (ae-forgotten-export) The symbol "MigrateRequest" needs to be exported by the entry point index.d.ts migrateDocsCase?(migrateRequest: MigrateRequest): Promise; // Warning: (ae-forgotten-export) The symbol "PublishRequest" needs to be exported by the entry point index.d.ts @@ -286,8 +280,4 @@ export class UrlPreparer implements PreparerBase { // Warnings were encountered during analysis: // // src/stages/generate/types.d.ts:45:5 - (ae-forgotten-export) The symbol "SupportedGeneratorKey" needs to be exported by the entry point index.d.ts -// src/stages/prepare/types.d.ts:18:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/stages/prepare/types.d.ts:19:8 - (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters -// src/stages/prepare/types.d.ts:21:33 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// src/stages/prepare/types.d.ts:21:16 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" ``` diff --git a/packages/techdocs-common/src/stages/generate/helpers.ts b/packages/techdocs-common/src/stages/generate/helpers.ts index 7c46f4e966..2debd5822c 100644 --- a/packages/techdocs-common/src/stages/generate/helpers.ts +++ b/packages/techdocs-common/src/stages/generate/helpers.ts @@ -86,9 +86,9 @@ export const runCommand = async ({ * Return the source url for MkDocs based on the backstage.io/techdocs-ref annotation. * Depending on the type of target, it can either return a repo_url, an edit_uri, both, or none. * - * @param {ParsedLocationAnnotation} parsedLocationAnnotation Object with location url and type - * @param {ScmIntegrationRegistry} scmIntegrations the scmIntegration to do url transformations - * @param {string} docsFolder the configured docs folder in the mkdocs.yml (defaults to 'docs') + * @param parsedLocationAnnotation - Object with location url and type + * @param scmIntegrations - the scmIntegration to do url transformations + * @param docsFolder - the configured docs folder in the mkdocs.yml (defaults to 'docs') * @returns the settings for the mkdocs.yml */ export const getRepoUrlFromLocationAnnotation = ( @@ -140,7 +140,7 @@ const MKDOCS_SCHEMA = DEFAULT_SCHEMA.extend([ * Finds and loads the contents of either an mkdocs.yml or mkdocs.yaml file, * depending on which is present (MkDocs supports both as of v1.2.2). * - * @param {string} inputDir base dir to be searched for either an mkdocs.yml or + * @param inputDir - base dir to be searched for either an mkdocs.yml or * mkdocs.yaml file. */ export const getMkdocsYml = async ( @@ -173,8 +173,8 @@ export const getMkdocsYml = async ( * Validating mkdocs config file for incorrect/insecure values * Throws on invalid configs * - * @param {string} inputDir base dir to be used as a docs_dir path validity check - * @param {string} mkdocsYmlFileString The string contents of the loaded + * @param inputDir - base dir to be used as a docs_dir path validity check + * @param mkdocsYmlFileString - The string contents of the loaded * mkdocs.yml or equivalent of a docs site * @returns the parsed docs_dir or undefined */ @@ -215,10 +215,10 @@ export const validateMkdocsYaml = async ( * This function will not throw an error since this is not critical to the whole TechDocs pipeline. * Instead it will log warnings if there are any errors in reading, parsing or writing YAML. * - * @param {string} mkdocsYmlPath Absolute path to mkdocs.yml or equivalent of a docs site - * @param {Logger} logger - * @param {ParsedLocationAnnotation} parsedLocationAnnotation Object with location url and type - * @param {ScmIntegrationRegistry} scmIntegrations the scmIntegration to do url transformations + * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site + * @param logger - A logger instance + * @param parsedLocationAnnotation - Object with location url and type + * @param scmIntegrations - the scmIntegration to do url transformations */ export const patchMkdocsYmlPreBuild = async ( mkdocsYmlPath: string, @@ -349,7 +349,7 @@ export const patchIndexPreBuild = async ({ * - The build_timestamp (now) * - The list of files generated * - * @param {string} techdocsMetadataPath File path to techdocs_metadata.json + * @param techdocsMetadataPath - File path to techdocs_metadata.json */ export const createOrUpdateMetadata = async ( techdocsMetadataPath: string, @@ -400,8 +400,8 @@ export const createOrUpdateMetadata = async ( * This is helpful to check if a TechDocs site in storage has gone outdated, without maintaining an in-memory build info * per Backstage instance. * - * @param {string} techdocsMetadataPath File path to techdocs_metadata.json - * @param {string} etag + * @param techdocsMetadataPath - File path to techdocs_metadata.json + * @param etag - The ETag to use */ export const storeEtagMetadata = async ( techdocsMetadataPath: string, diff --git a/packages/techdocs-common/src/stages/prepare/types.ts b/packages/techdocs-common/src/stages/prepare/types.ts index 5d46b5d235..5c219752fa 100644 --- a/packages/techdocs-common/src/stages/prepare/types.ts +++ b/packages/techdocs-common/src/stages/prepare/types.ts @@ -13,6 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + import type { Entity } from '@backstage/catalog-model'; import { Logger } from 'winston'; @@ -22,7 +23,7 @@ export type PreparerResponse = { */ preparedDir: string; /** - * A unique identifer of the tree blob, usually the commit SHA or etag from the target. + * A unique identifier of the tree blob, usually the commit SHA or etag from the target. */ etag: string; }; @@ -32,10 +33,10 @@ export type PreparerBase = { * Given an Entity definition from the Software Catalog, go and prepare a directory * with contents from the location in temporary storage and return the path. * - * @param entity The entity from the Software Catalog - * @param options.etag (Optional) If etag is provider, it will be used to check if the target has - * updated since the last build. - * @throws {NotModifiedError} when the prepared directory has not been changed since the last build. + * @param entity - The entity from the Software Catalog + * @param options - If etag is provided, it will be used to check if the target has + * updated since the last build. + * @throws `NotModifiedError` when the prepared directory has not been changed since the last build. */ prepare( entity: Entity, diff --git a/packages/techdocs-common/src/stages/publish/helpers.ts b/packages/techdocs-common/src/stages/publish/helpers.ts index bc7ed6b97d..cbecee51bc 100644 --- a/packages/techdocs-common/src/stages/publish/helpers.ts +++ b/packages/techdocs-common/src/stages/publish/helpers.ts @@ -42,7 +42,7 @@ export type responseHeadersType = { /** * Some files need special headers to be used correctly by the frontend. This function * generates headers in the response to those file requests. - * @param {string} fileExtension .html, .css, .js, .png etc. + * @param fileExtension - .html, .css, .js, .png etc. */ export const getHeadersForFileExtension = ( fileExtension: string, @@ -74,7 +74,7 @@ export const getHeadersForFileExtension = ( * '/User/username/my_dir/dirB/file2', * '/User/username/my_dir/file3' * ] - * @param rootDirPath Absolute path to the root directory. + * @param rootDirPath - Absolute path to the root directory. */ export const getFileTreeRecursively = async ( rootDirPath: string, diff --git a/packages/techdocs-common/src/stages/publish/types.ts b/packages/techdocs-common/src/stages/publish/types.ts index b7415722d6..37075a35a4 100644 --- a/packages/techdocs-common/src/stages/publish/types.ts +++ b/packages/techdocs-common/src/stages/publish/types.ts @@ -127,10 +127,10 @@ export interface PublisherBase { /** * Migrates documentation objects with case sensitive entity triplets to * lowercase entity triplets. This was (will be) a change introduced in - * techdocs-cli v{0.x.y} and techdocs-backend v{0.x.y}. + * `techdocs-cli` version `{0.x.y}` and `techdocs-backend` version `{0.x.y}`. * * Implementation of this method is unnecessary in publishers introduced - * after v{0.x.y} of techdocs-common. + * after version `{0.x.y}` of `techdocs-common`. */ migrateDocsCase?(migrateRequest: MigrateRequest): Promise; } diff --git a/plugins/apache-airflow/src/api/ApacheAirflowClient.ts b/plugins/apache-airflow/src/api/ApacheAirflowClient.ts index c184e304b4..847a1b1ca6 100644 --- a/plugins/apache-airflow/src/api/ApacheAirflowClient.ts +++ b/plugins/apache-airflow/src/api/ApacheAirflowClient.ts @@ -45,12 +45,12 @@ export class ApacheAirflowClient implements ApacheAirflowApi { * List all DAGs in the Airflow instance * * @remarks + * * All DAGs with a limit of 100 results per request are returned; this may be * bogged-down for instances with many DAGs, in which case table pagination * should be implemented * - * @param {number} objectsPerRequest records returned per request in pagination - * @returns {Promise} + * @param objectsPerRequest - records returned per request in pagination */ async listDags(options = { objectsPerRequest: 100 }): Promise { const dags: Dag[] = []; diff --git a/plugins/auth-backend/api-report.md b/plugins/auth-backend/api-report.md index ab8bd39a94..01de316de0 100644 --- a/plugins/auth-backend/api-report.md +++ b/plugins/auth-backend/api-report.md @@ -89,33 +89,13 @@ export type AuthProviderFactoryOptions = { catalogApi: CatalogApi; }; -// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag -// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag -// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag -// Warning: (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag // Warning: (ae-missing-release-tag) "AuthProviderRouteHandlers" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public export interface AuthProviderRouteHandlers { - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' frameHandler(req: express.Request, res: express.Response): Promise; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' logout?(req: express.Request, res: express.Response): Promise; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' refresh?(req: express.Request, res: express.Response): Promise; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' start(req: express.Request, res: express.Response): Promise; } @@ -502,28 +482,17 @@ export class OAuthEnvironmentHandler implements AuthProviderRouteHandlers { start(req: express.Request, res: express.Response): Promise; } -// Warning: (ae-missing-release-tag) "OAuthHandlers" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export interface OAuthHandlers { - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' handler(req: express.Request): Promise<{ response: OAuthResponse; refreshToken?: string; }>; logout?(): Promise; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' refresh?(req: OAuthRefreshRequest): Promise<{ response: OAuthResponse; refreshToken?: string; }>; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen start(req: OAuthStartRequest): Promise; } @@ -734,11 +703,6 @@ export type WebMessageResponse = // // src/identity/types.d.ts:31:9 - (ae-forgotten-export) The symbol "AnyJWK" needs to be exported by the entry point index.d.ts // src/providers/aws-alb/provider.d.ts:77:5 - (ae-forgotten-export) The symbol "AwsAlbResult" needs to be exported by the entry point index.d.ts -// src/providers/github/provider.d.ts:74:58 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag -// src/providers/github/provider.d.ts:74:90 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag -// src/providers/github/provider.d.ts:74:89 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// src/providers/github/provider.d.ts:74:67 - (tsdoc-malformed-html-name) Invalid HTML element: Expecting an HTML name -// src/providers/github/provider.d.ts:74:68 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" // src/providers/github/provider.d.ts:81:5 - (ae-forgotten-export) The symbol "StateEncoder" needs to be exported by the entry point index.d.ts -// src/providers/types.d.ts:100:5 - (ae-forgotten-export) The symbol "AuthProviderConfig" needs to be exported by the entry point index.d.ts +// src/providers/types.d.ts:88:5 - (ae-forgotten-export) The symbol "AuthProviderConfig" needs to be exported by the entry point index.d.ts ``` diff --git a/plugins/auth-backend/src/lib/oauth/types.ts b/plugins/auth-backend/src/lib/oauth/types.ts index f54d04d15b..9ddef007a7 100644 --- a/plugins/auth-backend/src/lib/oauth/types.ts +++ b/plugins/auth-backend/src/lib/oauth/types.ts @@ -103,18 +103,17 @@ export type OAuthRefreshRequest = express.Request<{}> & { * Any OAuth provider needs to implement this interface which has provider specific * handlers for different methods to perform authentication, get access tokens, * refresh tokens and perform sign out. + * + * @public */ export interface OAuthHandlers { /** - * This method initiates a sign in request with an auth provider. - * @param {express.Request} req - * @param options + * Initiate a sign in request with an auth provider. */ start(req: OAuthStartRequest): Promise; /** - * Handles the redirect from the auth provider when the user has signed in. - * @param {express.Request} req + * Handle the redirect from the auth provider when the user has signed in. */ handler(req: express.Request): Promise<{ response: OAuthResponse; @@ -123,8 +122,6 @@ export interface OAuthHandlers { /** * (Optional) Given a refresh token and scope fetches a new access token from the auth provider. - * @param {string} refreshToken - * @param {string} scope */ refresh?(req: OAuthRefreshRequest): Promise<{ response: OAuthResponse; diff --git a/plugins/auth-backend/src/providers/github/provider.ts b/plugins/auth-backend/src/providers/github/provider.ts index b832f4f77b..2984f144aa 100644 --- a/plugins/auth-backend/src/providers/github/provider.ts +++ b/plugins/auth-backend/src/providers/github/provider.ts @@ -222,7 +222,7 @@ export type GithubProviderOptions = { * Providing your own stateEncoder will allow you to add addition parameters to the state field. * * It is typed as follows: - * export type StateEncoder = (input: OAuthState) => Promise<{encodedState: string}>; + * `export type StateEncoder = (input: OAuthState) => Promise<{encodedState: string}>;` * * Note: the stateEncoder must encode a 'nonce' value and an 'env' value. Without this, the OAuth flow will fail * (These two values will be set by the req.state by default) diff --git a/plugins/auth-backend/src/providers/types.ts b/plugins/auth-backend/src/providers/types.ts index 0915bccc6c..dabe46a9ae 100644 --- a/plugins/auth-backend/src/providers/types.ts +++ b/plugins/auth-backend/src/providers/types.ts @@ -59,10 +59,10 @@ export type RedirectInfo = { * * The routes in the auth backend API are tied to these methods like below * - * /auth/[provider]/start -> start - * /auth/[provider]/handler/frame -> frameHandler - * /auth/[provider]/refresh -> refresh - * /auth/[provider]/logout -> logout + * `/auth/[provider]/start -> start` + * `/auth/[provider]/handler/frame -> frameHandler` + * `/auth/[provider]/refresh -> refresh` + * `/auth/[provider]/logout -> logout` */ export interface AuthProviderRouteHandlers { /** @@ -73,9 +73,6 @@ export interface AuthProviderRouteHandlers { * Response * - redirect to the auth provider for the user to sign in or consent. * - sets a nonce cookie and also pass the nonce as 'state' query parameter in the redirect request - * - * @param {express.Request} req - * @param {express.Response} res */ start(req: express.Request, res: express.Response): Promise; @@ -88,9 +85,6 @@ export interface AuthProviderRouteHandlers { * Response * - postMessage to the window with a payload that contains accessToken, expiryInSeconds?, idToken? and scope. * - sets a refresh token cookie if the auth provider supports refresh tokens - * - * @param {express.Request} req - * @param {express.Response} res */ frameHandler(req: express.Request, res: express.Response): Promise; @@ -102,9 +96,6 @@ export interface AuthProviderRouteHandlers { * - to contain a refresh token cookie and scope (Optional) query parameter. * Response * - payload with accessToken, expiryInSeconds?, idToken?, scope and user profile information. - * - * @param {express.Request} req - * @param {express.Response} res */ refresh?(req: express.Request, res: express.Response): Promise; @@ -113,9 +104,6 @@ export interface AuthProviderRouteHandlers { * * Response * - removes the refresh token cookie - * - * @param {express.Request} req - * @param {express.Response} res */ logout?(req: express.Request, res: express.Response): Promise; } diff --git a/plugins/azure-devops/src/components/PullRequestsPage/lib/utils.ts b/plugins/azure-devops/src/components/PullRequestsPage/lib/utils.ts index c4fcdc9f7e..4b7a6b2e7f 100644 --- a/plugins/azure-devops/src/components/PullRequestsPage/lib/utils.ts +++ b/plugins/azure-devops/src/components/PullRequestsPage/lib/utils.ts @@ -28,7 +28,7 @@ import { /** * Filters a reviewer based on vote status and if the reviewer is required. - * @param reviewer a reviewer to filter. + * @param reviewer - a reviewer to filter. * @returns whether or not to filter the `reviewer`. */ export function reviewerFilter(reviewer: Reviewer): boolean { @@ -39,8 +39,8 @@ export function reviewerFilter(reviewer: Reviewer): boolean { /** * Removes values from the provided array and returns them. - * @param arr the array to extract values from. - * @param filter a filter used to extract values from the provided array. + * @param arr - the array to extract values from. + * @param filter - a filter used to extract values from the provided array. * @returns the values that were extracted from the array. * * @example @@ -80,8 +80,8 @@ export function arrayExtract(arr: T[], filter: (value: T) => unknown): T[] { /** * Creates groups of pull requests based on a list of `PullRequestGroupConfig`. - * @param pullRequests all pull requests to be split up into groups. - * @param configs the config used for splitting up the pull request groups. + * @param pullRequests - all pull requests to be split up into groups. + * @param configs - the config used for splitting up the pull request groups. * @returns a list of pull request groups. */ export function getPullRequestGroups( diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index 4b4036ee8a..c9444f3506 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -251,9 +251,7 @@ export class BuiltinKindsEntityProcessor implements CatalogProcessor { export class CatalogBuilder { // @deprecated constructor(env: CatalogEnvironment); - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen addEntityPolicy(...policies: EntityPolicy[]): CatalogBuilder; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen addProcessor(...processors: CatalogProcessor[]): CatalogBuilder; build(): Promise<{ entitiesCatalog: EntitiesCatalog; @@ -263,16 +261,10 @@ export class CatalogBuilder { }>; // (undocumented) static create(env: CatalogEnvironment): Promise; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen replaceEntityPolicies(policies: EntityPolicy[]): CatalogBuilder; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen replaceProcessors(processors: CatalogProcessor[]): CatalogBuilder; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen setEntityDataParser(parser: CatalogProcessorParser): CatalogBuilder; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen setFieldFormatValidators(validators: Partial): CatalogBuilder; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen setPlaceholderResolver( key: string, resolver: PlaceholderResolver, @@ -541,8 +533,6 @@ export function createNextRouter( options: NextRouterOptions, ): Promise; -// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" // Warning: (ae-missing-release-tag) "createRandomRefreshInterval" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public @@ -831,7 +821,6 @@ export type DeferredEntity = { locationKey?: string; }; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // Warning: (ae-missing-release-tag) "durationText" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public @@ -1145,7 +1134,6 @@ export class HigherOrderOperations implements HigherOrderOperation { locationReader: LocationReader, logger: Logger_2, ); - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen addLocation( spec: LocationSpec, options?: { @@ -1306,9 +1294,7 @@ export type LocationUpdateStatus = { // @public export class NextCatalogBuilder { constructor(env: CatalogEnvironment); - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen addEntityPolicy(...policies: EntityPolicy[]): NextCatalogBuilder; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen addEntityProvider(...providers: EntityProvider[]): NextCatalogBuilder; addPermissionRules( ...permissionRules: PermissionRule< @@ -1317,7 +1303,6 @@ export class NextCatalogBuilder { unknown[] >[] ): void; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen addProcessor(...processors: CatalogProcessor[]): NextCatalogBuilder; build(): Promise<{ entitiesCatalog: EntitiesCatalog; @@ -1328,17 +1313,11 @@ export class NextCatalogBuilder { router: Router; }>; getDefaultProcessors(): CatalogProcessor[]; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen replaceEntityPolicies(policies: EntityPolicy[]): NextCatalogBuilder; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen replaceProcessors(processors: CatalogProcessor[]): NextCatalogBuilder; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen setEntityDataParser(parser: CatalogProcessorParser): NextCatalogBuilder; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen setFieldFormatValidators(validators: Partial): NextCatalogBuilder; setLocationAnalyzer(locationAnalyzer: LocationAnalyzer): NextCatalogBuilder; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen setPlaceholderResolver( key: string, resolver: PlaceholderResolver, @@ -1563,8 +1542,6 @@ export interface RouterOptions { refreshService?: RefreshService; } -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // Warning: (ae-missing-release-tag) "runPeriodically" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public @@ -1612,20 +1589,5 @@ export class UrlReaderProcessor implements CatalogProcessor { // Warnings were encountered during analysis: // -// src/catalog/types.d.ts:94:8 - (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters -// src/catalog/types.d.ts:95:8 - (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters -// src/catalog/types.d.ts:96:8 - (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters // src/ingestion/processors/GithubMultiOrgReaderProcessor.d.ts:23:9 - (ae-forgotten-export) The symbol "GithubMultiOrgConfig" needs to be exported by the entry point index.d.ts -// src/ingestion/types.d.ts:8:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/legacy/database/types.d.ts:98:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/legacy/database/types.d.ts:104:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/legacy/database/types.d.ts:105:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/legacy/database/types.d.ts:119:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/legacy/database/types.d.ts:120:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/legacy/database/types.d.ts:121:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/legacy/database/types.d.ts:123:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/legacy/database/types.d.ts:136:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/legacy/database/types.d.ts:137:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/legacy/database/types.d.ts:138:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/legacy/ingestion/types.d.ts:19:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen ``` diff --git a/plugins/catalog-backend/src/catalog/types.ts b/plugins/catalog-backend/src/catalog/types.ts index 2a18783679..f030d63bce 100644 --- a/plugins/catalog-backend/src/catalog/types.ts +++ b/plugins/catalog-backend/src/catalog/types.ts @@ -117,12 +117,7 @@ export type EntitiesCatalog = { /** * Writes a number of entities efficiently to storage. * - * @deprecated This method was part of the legacy catalog engine an will be removed. - * - * @param requests - The entities and their relations - * @param options.locationId - The location that they all belong to (default none) - * @param options.dryRun - Whether to throw away the results (default false) - * @param options.outputEntities - Whether to return the resulting entities (default false) + * @deprecated This method was part of the legacy catalog engine and will be removed. */ batchAddOrUpdateEntities?( requests: EntityUpsertRequest[], diff --git a/plugins/catalog-backend/src/ingestion/processors/github/github.ts b/plugins/catalog-backend/src/ingestion/processors/github/github.ts index 547568d8d2..b3dae26091 100644 --- a/plugins/catalog-backend/src/ingestion/processors/github/github.ts +++ b/plugins/catalog-backend/src/ingestion/processors/github/github.ts @@ -75,8 +75,8 @@ export type Connection = { * * Note that the users will not have their memberships filled in. * - * @param client An octokit graphql client - * @param org The slug of the org to read + * @param client - An octokit graphql client + * @param org - The slug of the org to read */ export async function getOrganizationUsers( client: typeof graphql, @@ -143,8 +143,8 @@ export async function getOrganizationUsers( * * Note that the teams will not have any relations apart from parent filled in. * - * @param client An octokit graphql client - * @param org The slug of the org to read + * @param client - An octokit graphql client + * @param org - The slug of the org to read */ export async function getOrganizationTeams( client: typeof graphql, @@ -285,9 +285,9 @@ export async function getOrganizationRepositories( * * Note that the users will not have their memberships filled in. * - * @param client An octokit graphql client - * @param org The slug of the org to read - * @param teamSlug The slug of the team to read + * @param client - An octokit graphql client + * @param org - The slug of the org to read + * @param teamSlug - The slug of the team to read */ export async function getTeamMembers( client: typeof graphql, @@ -326,13 +326,13 @@ export async function getTeamMembers( * * Requires that the query accepts a $cursor variable. * - * @param client The octokit client - * @param query The query to execute - * @param connection A function that, given the response, picks out the actual + * @param client - The octokit client + * @param query - The query to execute + * @param connection - A function that, given the response, picks out the actual * Connection object that's being iterated - * @param mapper A function that, given one of the nodes in the Connection, + * @param mapper - A function that, given one of the nodes in the Connection, * returns the model mapped form of it - * @param variables The variable values that the query needs, minus the cursor + * @param variables - The variable values that the query needs, minus the cursor */ export async function queryWithPaging< GraphqlType, diff --git a/plugins/catalog-backend/src/ingestion/types.ts b/plugins/catalog-backend/src/ingestion/types.ts index f353dd3818..30cdee4760 100644 --- a/plugins/catalog-backend/src/ingestion/types.ts +++ b/plugins/catalog-backend/src/ingestion/types.ts @@ -26,7 +26,7 @@ export type LocationAnalyzer = { * Generates an entity configuration for given git repository. It's used for * importing new component to the backstage app. * - * @param location Git repository to analyze and generate config for. + * @param location - Git repository to analyze and generate config for. */ analyzeLocation( location: AnalyzeLocationRequest, diff --git a/plugins/catalog-backend/src/legacy/database/search.ts b/plugins/catalog-backend/src/legacy/database/search.ts index 73bf02c1f9..f9366322a4 100644 --- a/plugins/catalog-backend/src/legacy/database/search.ts +++ b/plugins/catalog-backend/src/legacy/database/search.ts @@ -149,8 +149,8 @@ export function mapToRows( /** * Generates all of the search rows that are relevant for this entity. * - * @param entityId The uid of the entity - * @param entity The entity + * @param entityId - The uid of the entity + * @param entity - The entity * @returns A list of entity search rows */ export function buildEntitySearch( diff --git a/plugins/catalog-backend/src/legacy/database/types.ts b/plugins/catalog-backend/src/legacy/database/types.ts index b68681b4bd..c2454df261 100644 --- a/plugins/catalog-backend/src/legacy/database/types.ts +++ b/plugins/catalog-backend/src/legacy/database/types.ts @@ -132,15 +132,15 @@ export type Database = { * The callback is expected to make calls back into this class. When it * completes, the transaction is closed. * - * @param fn The callback that implements the transaction + * @param fn - The callback that implements the transaction */ transaction(fn: (tx: Transaction) => Promise): Promise; /** * Adds a set of new entities to the catalog. * - * @param tx An ongoing transaction - * @param request The entities being added + * @param tx - An ongoing transaction + * @param request - The entities being added */ addEntities( tx: Transaction, @@ -158,11 +158,11 @@ export type Database = { * account. Attempts to update a matching entity, but where the etag and/or * generation are not equal to the passed values, will fail. * - * @param tx An ongoing transaction - * @param request The entity being updated - * @param matchingEtag If specified, reject with ConflictError if not + * @param tx - An ongoing transaction + * @param request - The entity being updated + * @param matchingEtag - If specified, reject with ConflictError if not * matching the entry in the database - * @param matchingGeneration If specified, reject with ConflictError if not + * @param matchingGeneration - If specified, reject with ConflictError if not * matching the entry in the database * @returns The updated entity */ @@ -194,9 +194,9 @@ export type Database = { * Remove current relations for the entity and replace them with the new * relations array. * - * @param tx An ongoing transaction - * @param entityUid The entity uid - * @param relations The relationships to be set + * @param tx - An ongoing transaction + * @param entityUid - The entity uid + * @param relations - The relationships to be set */ setRelations( tx: Transaction, diff --git a/plugins/catalog-backend/src/legacy/ingestion/HigherOrderOperations.ts b/plugins/catalog-backend/src/legacy/ingestion/HigherOrderOperations.ts index 9189b91fe8..e57f149485 100644 --- a/plugins/catalog-backend/src/legacy/ingestion/HigherOrderOperations.ts +++ b/plugins/catalog-backend/src/legacy/ingestion/HigherOrderOperations.ts @@ -54,7 +54,7 @@ export class HigherOrderOperations implements HigherOrderOperation { * If the location already existed, the old location is returned instead and * the catalog is left unchanged. * - * @param spec The location to add + * @param spec - The location to add */ async addLocation( spec: LocationSpec, diff --git a/plugins/catalog-backend/src/legacy/ingestion/types.ts b/plugins/catalog-backend/src/legacy/ingestion/types.ts index b2dbab4a3a..0a02a5e17e 100644 --- a/plugins/catalog-backend/src/legacy/ingestion/types.ts +++ b/plugins/catalog-backend/src/legacy/ingestion/types.ts @@ -49,7 +49,7 @@ export type LocationReader = { /** * Reads the contents of a location. * - * @param location The location to read + * @param location - The location to read * @throws An error if the location was handled by this reader, but could not * be read */ diff --git a/plugins/catalog-backend/src/legacy/service/CatalogBuilder.ts b/plugins/catalog-backend/src/legacy/service/CatalogBuilder.ts index 6fb52e245e..f1f902ef48 100644 --- a/plugins/catalog-backend/src/legacy/service/CatalogBuilder.ts +++ b/plugins/catalog-backend/src/legacy/service/CatalogBuilder.ts @@ -129,7 +129,7 @@ export class CatalogBuilder { * in various core entity fields (such as metadata.name), you may want to use * {@link CatalogBuilder#setFieldFormatValidators} instead. * - * @param policies One or more policies + * @param policies - One or more policies */ addEntityPolicy(...policies: EntityPolicy[]): CatalogBuilder { this.entityPolicies.push(...policies); @@ -147,7 +147,7 @@ export class CatalogBuilder { * * This function replaces the default set of policies; use with care. * - * @param policies One or more policies + * @param policies - One or more policies */ replaceEntityPolicies(policies: EntityPolicy[]): CatalogBuilder { this.entityPolicies = [...policies]; @@ -159,8 +159,8 @@ export class CatalogBuilder { * Adds, or overwrites, a handler for placeholders (e.g. $file) in entity * definition files. * - * @param key The key that identifies the placeholder, e.g. "file" - * @param resolver The resolver that gets values for this placeholder + * @param key - The key that identifies the placeholder, e.g. "file" + * @param resolver - The resolver that gets values for this placeholder */ setPlaceholderResolver( key: string, @@ -178,7 +178,7 @@ export class CatalogBuilder { * This function has no effect if used together with * {@link CatalogBuilder#replaceEntityPolicies}. * - * @param validators The (subset of) validators to set + * @param validators - The (subset of) validators to set */ setFieldFormatValidators(validators: Partial): CatalogBuilder { lodash.merge(this.fieldFormatValidators, validators); @@ -189,7 +189,7 @@ export class CatalogBuilder { * Adds entity processors. These are responsible for reading, parsing, and * processing entities before they are persisted in the catalog. * - * @param processors One or more processors + * @param processors - One or more processors */ addProcessor(...processors: CatalogProcessor[]): CatalogBuilder { this.processors.push(...processors); @@ -202,7 +202,7 @@ export class CatalogBuilder { * * This function replaces the default set of processors; use with care. * - * @param processors One or more processors + * @param processors - One or more processors */ replaceProcessors(processors: CatalogProcessor[]): CatalogBuilder { this.processors = [...processors]; @@ -217,7 +217,7 @@ export class CatalogBuilder { * specification data has been read from a remote source, and needs to be * parsed and emitted as structured data. * - * @param parser The custom parser + * @param parser - The custom parser */ setEntityDataParser(parser: CatalogProcessorParser): CatalogBuilder { this.parser = parser; diff --git a/plugins/catalog-backend/src/processing/TaskPipeline.ts b/plugins/catalog-backend/src/processing/TaskPipeline.ts index 53283dc9c5..4afe2408a8 100644 --- a/plugins/catalog-backend/src/processing/TaskPipeline.ts +++ b/plugins/catalog-backend/src/processing/TaskPipeline.ts @@ -56,7 +56,7 @@ type Options = { * Creates a task processing pipeline which continuously loads in tasks to * keep the number of parallel in-flight tasks between a low and high watermark. * - * @param options The options for the pipeline. + * @param options - The options for the pipeline. * @returns A stop function which when called halts all processing. */ export function startTaskPipeline(options: Options) { diff --git a/plugins/catalog-backend/src/processing/refresh.ts b/plugins/catalog-backend/src/processing/refresh.ts index aae992f391..c60f42ff96 100644 --- a/plugins/catalog-backend/src/processing/refresh.ts +++ b/plugins/catalog-backend/src/processing/refresh.ts @@ -21,7 +21,7 @@ export type RefreshIntervalFunction = () => number; /** * Creates a function that returns a random refresh interval between minSeconds and maxSeconds. - * @returns {RefreshIntervalFunction} that provides the next refresh interval + * @returns A {@link RefreshIntervalFunction} that provides the next refresh interval */ export function createRandomRefreshInterval(options: { minSeconds: number; diff --git a/plugins/catalog-backend/src/service/NextCatalogBuilder.ts b/plugins/catalog-backend/src/service/NextCatalogBuilder.ts index 36d4347ede..3a13764bdd 100644 --- a/plugins/catalog-backend/src/service/NextCatalogBuilder.ts +++ b/plugins/catalog-backend/src/service/NextCatalogBuilder.ts @@ -159,7 +159,7 @@ export class NextCatalogBuilder { * in various core entity fields (such as metadata.name), you may want to use * {@link NextCatalogBuilder#setFieldFormatValidators} instead. * - * @param policies One or more policies + * @param policies - One or more policies */ addEntityPolicy(...policies: EntityPolicy[]): NextCatalogBuilder { this.entityPolicies.push(...policies); @@ -210,7 +210,7 @@ export class NextCatalogBuilder { * * This function replaces the default set of policies; use with care. * - * @param policies One or more policies + * @param policies - One or more policies */ replaceEntityPolicies(policies: EntityPolicy[]): NextCatalogBuilder { this.entityPolicies = [...policies]; @@ -222,8 +222,8 @@ export class NextCatalogBuilder { * Adds, or overwrites, a handler for placeholders (e.g. $file) in entity * definition files. * - * @param key The key that identifies the placeholder, e.g. "file" - * @param resolver The resolver that gets values for this placeholder + * @param key - The key that identifies the placeholder, e.g. "file" + * @param resolver - The resolver that gets values for this placeholder */ setPlaceholderResolver( key: string, @@ -241,7 +241,7 @@ export class NextCatalogBuilder { * This function has no effect if used together with * {@link NextCatalogBuilder#replaceEntityPolicies}. * - * @param validators The (subset of) validators to set + * @param validators - The (subset of) validators to set */ setFieldFormatValidators( validators: Partial, @@ -257,7 +257,7 @@ export class NextCatalogBuilder { * stored locations. If you ingest entities out of a third party system, you * may want to implement that in terms of an entity provider as well. * - * @param providers One or more entity providers + * @param providers - One or more entity providers */ addEntityProvider(...providers: EntityProvider[]): NextCatalogBuilder { this.entityProviders.push(...providers); @@ -268,7 +268,7 @@ export class NextCatalogBuilder { * Adds entity processors. These are responsible for reading, parsing, and * processing entities before they are persisted in the catalog. * - * @param processors One or more processors + * @param processors - One or more processors */ addProcessor(...processors: CatalogProcessor[]): NextCatalogBuilder { this.processors.push(...processors); @@ -282,7 +282,7 @@ export class NextCatalogBuilder { * This function replaces the default set of processors, consider using with * {@link NextCatalogBuilder#getDefaultProcessors}; use with care. * - * @param processors One or more processors + * @param processors - One or more processors */ replaceProcessors(processors: CatalogProcessor[]): NextCatalogBuilder { this.processors = [...processors]; @@ -322,7 +322,7 @@ export class NextCatalogBuilder { * specification data has been read from a remote source, and needs to be * parsed and emitted as structured data. * - * @param parser The custom parser + * @param parser - The custom parser */ setEntityDataParser(parser: CatalogProcessorParser): NextCatalogBuilder { this.parser = parser; diff --git a/plugins/catalog-backend/src/stitching/buildEntitySearch.ts b/plugins/catalog-backend/src/stitching/buildEntitySearch.ts index b6c3eead2a..84c6036013 100644 --- a/plugins/catalog-backend/src/stitching/buildEntitySearch.ts +++ b/plugins/catalog-backend/src/stitching/buildEntitySearch.ts @@ -154,8 +154,8 @@ export function mapToRows(input: Kv[], entityId: string): DbSearchRow[] { /** * Generates all of the search rows that are relevant for this entity. * - * @param entityId The uid of the entity - * @param entity The entity + * @param entityId - The uid of the entity + * @param entity - The entity * @returns A list of entity search rows */ export function buildEntitySearch( diff --git a/plugins/catalog-backend/src/util/runPeriodically.ts b/plugins/catalog-backend/src/util/runPeriodically.ts index d5f5f87d7f..2f3104e221 100644 --- a/plugins/catalog-backend/src/util/runPeriodically.ts +++ b/plugins/catalog-backend/src/util/runPeriodically.ts @@ -19,8 +19,8 @@ * * Supports async functions, and silently ignores exceptions and rejections. * - * @param fn The function to run. May return a Promise. - * @param delayMs The delay between a completed function invocation and the + * @param fn - The function to run. May return a Promise. + * @param delayMs - The delay between a completed function invocation and the * next. * @returns A function that, when called, stops the invocation loop. */ diff --git a/plugins/catalog-backend/src/util/timing.ts b/plugins/catalog-backend/src/util/timing.ts index 0b9498a24c..b5f9eb258f 100644 --- a/plugins/catalog-backend/src/util/timing.ts +++ b/plugins/catalog-backend/src/util/timing.ts @@ -18,7 +18,7 @@ * Returns a string with the elapsed time since the start of an operation, * with some human friendly precision, e.g. "133ms" or "14.5s". * - * @param startTimestamp The timestamp (from process.hrtime()) at the start ot + * @param startTimestamp - The timestamp (from process.hrtime()) at the start ot * the operation */ export function durationText(startTimestamp: [number, number]): string { diff --git a/plugins/catalog-import/api-report.md b/plugins/catalog-import/api-report.md index 9874956b5f..a1ad76f323 100644 --- a/plugins/catalog-import/api-report.md +++ b/plugins/catalog-import/api-report.md @@ -143,8 +143,6 @@ const catalogImportPlugin: BackstagePlugin< export { catalogImportPlugin }; export { catalogImportPlugin as plugin }; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // Warning: (ae-forgotten-export) The symbol "ImportFlows" needs to be exported by the entry point index.d.ts // Warning: (ae-forgotten-export) The symbol "StepperProvider" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "defaultGenerateStepper" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) @@ -188,9 +186,6 @@ export const ImportStepper: ({ variant, }: Props_2) => JSX.Element; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "PreparePullRequestForm" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -223,9 +218,6 @@ export const PreviewPullRequestComponent: ({ classes, }: Props_7) => JSX.Element; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "StepInitAnalyzeUrl" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // diff --git a/plugins/catalog-import/src/components/ImportStepper/defaults.tsx b/plugins/catalog-import/src/components/ImportStepper/defaults.tsx index 357ed64e14..553e8977b8 100644 --- a/plugins/catalog-import/src/components/ImportStepper/defaults.tsx +++ b/plugins/catalog-import/src/components/ImportStepper/defaults.tsx @@ -67,8 +67,8 @@ export type StepperProvider = { * Override this function to customize the import flow. Each flow should at * least override the prepare operation. * - * @param flow the name of the active flow - * @param defaults the default steps + * @param flow - the name of the active flow + * @param defaults - the default steps */ export function defaultGenerateStepper( flow: ImportFlows, diff --git a/plugins/catalog-import/src/components/StepInitAnalyzeUrl/StepInitAnalyzeUrl.tsx b/plugins/catalog-import/src/components/StepInitAnalyzeUrl/StepInitAnalyzeUrl.tsx index 7784aa7284..63f3c10fe3 100644 --- a/plugins/catalog-import/src/components/StepInitAnalyzeUrl/StepInitAnalyzeUrl.tsx +++ b/plugins/catalog-import/src/components/StepInitAnalyzeUrl/StepInitAnalyzeUrl.tsx @@ -41,9 +41,9 @@ type Props = { /** * A form that lets the user input a url and analyze it for existing locations or potential entities. * - * @param onAnalysis is called when the analysis was successful - * @param analysisUrl a url that can be used as a default value - * @param disablePullRequest if true, repositories without entities will abort the wizard + * @param onAnalysis - is called when the analysis was successful + * @param analysisUrl - a url that can be used as a default value + * @param disablePullRequest - if true, repositories without entities will abort the wizard */ export const StepInitAnalyzeUrl = ({ onAnalysis, diff --git a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreparePullRequestForm.tsx b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreparePullRequestForm.tsx index a1a20381f9..f3974a8c2d 100644 --- a/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreparePullRequestForm.tsx +++ b/plugins/catalog-import/src/components/StepPrepareCreatePullRequest/PreparePullRequestForm.tsx @@ -44,10 +44,10 @@ type Props> = Pick< * A form wrapper that creates a form that is used to prepare a pull request. It * hosts the form logic. * - * @param defaultValues the default values of the form - * @param onSubmit a callback that is executed when the form is submitted + * @param defaultValues - the default values of the form + * @param onSubmit - a callback that is executed when the form is submitted * (initiated by a button of type="submit") - * @param render render the form elements + * @param render - render the form elements */ export const PreparePullRequestForm = < TFieldValues extends Record, diff --git a/plugins/catalog-import/src/components/StepPrepareSelectLocations/StepPrepareSelectLocations.tsx b/plugins/catalog-import/src/components/StepPrepareSelectLocations/StepPrepareSelectLocations.tsx index e7bedef9cc..210b49d188 100644 --- a/plugins/catalog-import/src/components/StepPrepareSelectLocations/StepPrepareSelectLocations.tsx +++ b/plugins/catalog-import/src/components/StepPrepareSelectLocations/StepPrepareSelectLocations.tsx @@ -40,10 +40,10 @@ type Props = { /** * A form that lets a user select one of a list of locations to import * - * @param analyzeResult the result of the analysis - * @param prepareResult the selectected locations from a previous step - * @param onPrepare called after the selection - * @param onGoBack called to go back to the previous step + * @param analyzeResult - the result of the analysis + * @param prepareResult - the selectected locations from a previous step + * @param onPrepare - called after the selection + * @param onGoBack - called to go back to the previous step */ export const StepPrepareSelectLocations = ({ analyzeResult, diff --git a/plugins/catalog-import/src/components/useImportState.ts b/plugins/catalog-import/src/components/useImportState.ts index b5fa007144..a1505b26b5 100644 --- a/plugins/catalog-import/src/components/useImportState.ts +++ b/plugins/catalog-import/src/components/useImportState.ts @@ -247,7 +247,7 @@ function reducer(state: ReducerState, action: ReducerActions): ReducerState { * 3. review * 4. finish * - * @param options options + * @param options - options */ export const useImportState = (options?: { initialUrl?: string; diff --git a/plugins/catalog-react/api-report.md b/plugins/catalog-react/api-report.md index 673d9256f1..b57ec4da19 100644 --- a/plugins/catalog-react/api-report.md +++ b/plugins/catalog-react/api-report.md @@ -713,7 +713,6 @@ export const EntityTypePicker: ( props: EntityTypeFilterProps, ) => JSX.Element | null; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "FavoriteEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -966,15 +965,4 @@ export function useStarredEntity(entityOrRef: Entity | EntityName | string): { toggleStarredEntity: () => void; isStarredEntity: boolean; }; - -// Warnings were encountered during analysis: -// -// src/types.d.ts:6:49 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// src/types.d.ts:6:10 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" -// src/types.d.ts:7:75 - (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// src/types.d.ts:7:10 - (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" -// src/types.d.ts:15:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/types.d.ts:16:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/types.d.ts:22:68 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag -// src/types.d.ts:22:88 - (tsdoc-escape-greater-than) The ">" character should be escaped using a backslash to avoid confusion with an HTML tag ``` diff --git a/plugins/catalog-react/src/components/FavoriteEntity/FavoriteEntity.tsx b/plugins/catalog-react/src/components/FavoriteEntity/FavoriteEntity.tsx index db60c34b66..730c9a2378 100644 --- a/plugins/catalog-react/src/components/FavoriteEntity/FavoriteEntity.tsx +++ b/plugins/catalog-react/src/components/FavoriteEntity/FavoriteEntity.tsx @@ -37,7 +37,7 @@ export const favoriteEntityIcon = (isStarred: boolean) => /** * IconButton for showing if a current entity is starred and adding/removing it from the favorite entities - * @param props MaterialUI IconButton props extended by required `entity` prop + * @param props - MaterialUI IconButton props extended by required `entity` prop */ export const FavoriteEntity = (props: Props) => { const { toggleStarredEntity, isStarredEntity } = useStarredEntity( diff --git a/plugins/catalog-react/src/types.ts b/plugins/catalog-react/src/types.ts index c5612fdf3f..964858cb10 100644 --- a/plugins/catalog-react/src/types.ts +++ b/plugins/catalog-react/src/types.ts @@ -20,8 +20,8 @@ export type EntityFilter = { /** * Get filters to add to the catalog-backend request. These are a dot-delimited field with * value(s) to accept, extracted on the backend by parseEntityFilterParams. For example: - * { field: 'kind', values: ['component'] } - * { field: 'metadata.name', values: ['component-1', 'component-2'] } + * `{ field: 'kind', values: ['component'] }` + * `{ field: 'metadata.name', values: ['component-1', 'component-2'] }` */ getCatalogFilters?: () => Record< string, @@ -32,16 +32,13 @@ export type EntityFilter = { * Filter entities on the frontend after a catalog-backend request. This function will be called * with each backend-resolved entity. This is used when frontend information is required for * filtering, such as a user's starred entities. - * - * @param entity - * @param env */ filterEntity?: (entity: Entity) => boolean; /** * Serialize the filter value to a string for query params. The UI component responsible for * handling this filter should retrieve this from useEntityListProvider.queryParameters. The - * value restored should be in the precedence: queryParameters > initialValue prop > default. + * value restored should be in the precedence: queryParameters `>` initialValue prop `>` default. */ toQueryValue?: () => string | string[]; }; diff --git a/plugins/code-coverage-backend/src/service/converter/cobertura.ts b/plugins/code-coverage-backend/src/service/converter/cobertura.ts index 12893a397d..e7f7490304 100644 --- a/plugins/code-coverage-backend/src/service/converter/cobertura.ts +++ b/plugins/code-coverage-backend/src/service/converter/cobertura.ts @@ -26,8 +26,8 @@ export class Cobertura implements Converter { /** * convert cobertura into shared json coverage format * - * @param xml cobertura xml object - * @param scmFiles list of files that are commited to SCM + * @param xml - cobertura xml object + * @param scmFiles - list of files that are commited to SCM */ convert(xml: CoberturaXML, scmFiles: string[]): FileEntry[] { const ppc = xml.coverage.packages @@ -84,7 +84,7 @@ export class Cobertura implements Converter { /** * Parses branch coverage information from condition-coverage * - * @param condition condition-coverage value from line coverage + * @param condition - condition-coverage value from line coverage */ private parseBranch(condition: string): BranchHit | null { const pattern = /[0-9\.]+\%\s\(([0-9]+)\/([0-9]+)\)/; @@ -104,7 +104,7 @@ export class Cobertura implements Converter { /** * Extract line hits from a class coverage entry * - * @param clz class coverage information + * @param clz - class coverage information */ private extractLines(clz: InnerClass): Array { const classLines = clz.lines.flatMap(l => l.line); diff --git a/plugins/code-coverage-backend/src/service/converter/jacoco.ts b/plugins/code-coverage-backend/src/service/converter/jacoco.ts index c252c00d4e..f3047d9f00 100644 --- a/plugins/code-coverage-backend/src/service/converter/jacoco.ts +++ b/plugins/code-coverage-backend/src/service/converter/jacoco.ts @@ -34,8 +34,8 @@ export class Jacoco implements Converter { /** * Converts jacoco into shared json coverage format * - * @param xml jacoco xml object - * @param scmFiles list of files that are committed to SCM + * @param xml - jacoco xml object + * @param scmFiles - list of files that are committed to SCM */ convert(xml: JacocoXML, scmFiles: Array): Array { const jscov: Array = []; diff --git a/plugins/code-coverage/src/components/FileExplorer/Highlighter.ts b/plugins/code-coverage/src/components/FileExplorer/Highlighter.ts index 3cb20ad5a7..225ca96175 100644 --- a/plugins/code-coverage/src/components/FileExplorer/Highlighter.ts +++ b/plugins/code-coverage/src/components/FileExplorer/Highlighter.ts @@ -20,8 +20,8 @@ import highlight from 'highlight.js'; * Given a file extension, repo name, and array of code lines, return a Promise resolving * to an array of formatted lines with html/css formatting. * - * @param fileExtension The extension of the source file - * @param lines The source code lines + * @param fileExtension - The extension of the source file + * @param lines - The source code lines * * @returns Promise of formatted lines * diff --git a/plugins/cost-insights/api-report.md b/plugins/cost-insights/api-report.md index f15264f838..75e1315502 100644 --- a/plugins/cost-insights/api-report.md +++ b/plugins/cost-insights/api-report.md @@ -817,16 +817,4 @@ export interface UnlabeledDataflowData { // (undocumented) unlabeledCost: number; } - -// Warnings were encountered during analysis: -// -// src/api/CostInsightsApi.d.ts:34:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/api/CostInsightsApi.d.ts:42:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/api/CostInsightsApi.d.ts:56:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/api/CostInsightsApi.d.ts:57:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/api/CostInsightsApi.d.ts:73:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/api/CostInsightsApi.d.ts:74:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/api/CostInsightsApi.d.ts:83:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/api/CostInsightsApi.d.ts:84:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// src/api/CostInsightsApi.d.ts:100:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen ``` diff --git a/plugins/cost-insights/src/api/CostInsightsApi.ts b/plugins/cost-insights/src/api/CostInsightsApi.ts index 58c8592273..558cb57c0e 100644 --- a/plugins/cost-insights/src/api/CostInsightsApi.ts +++ b/plugins/cost-insights/src/api/CostInsightsApi.ts @@ -62,7 +62,7 @@ export type CostInsightsApi = { * * This method should be removed once the Backstage identity plugin provides the same concept. * - * @param userId The login id for the current user + * @param userId - The login id for the current user */ getUserGroups(userId: string): Promise; @@ -71,7 +71,7 @@ export type CostInsightsApi = { * similar concept in billing accounts). These act as filters for the displayed costs, users can * choose whether they see all costs for a group, or those from a particular owned project. * - * @param group The group id from getUserGroups or query parameters + * @param group - The group id from getUserGroups or query parameters */ getGroupProjects(group: string): Promise; @@ -86,8 +86,8 @@ export type CostInsightsApi = { * The rate of change in this comparison allows teams to reason about their cost growth (or * reduction) and compare it to metrics important to the business. * - * @param group The group id from getUserGroups or query parameters - * @param intervals An ISO 8601 repeating interval string, such as R2/P30D/2020-09-01 + * @param group - The group id from getUserGroups or query parameters + * @param intervals - An ISO 8601 repeating interval string, such as R2/P30D/2020-09-01 * https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals */ getGroupDailyCost(group: string, intervals: string): Promise; @@ -104,8 +104,8 @@ export type CostInsightsApi = { * The rate of change in this comparison allows teams to reason about the project's cost growth * (or reduction) and compare it to metrics important to the business. * - * @param project The project id from getGroupProjects or query parameters - * @param intervals An ISO 8601 repeating interval string, such as R2/P30D/2020-09-01 + * @param project - The project id from getGroupProjects or query parameters + * @param intervals - An ISO 8601 repeating interval string, such as R2/P30D/2020-09-01 * https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals */ getProjectDailyCost(project: string, intervals: string): Promise; @@ -115,8 +115,8 @@ export type CostInsightsApi = { * can see metrics important to their business in comparison to the growth * (or reduction) of a project or group's daily costs. * - * @param metric A metric from the cost-insights configuration in app-config.yaml. - * @param intervals An ISO 8601 repeating interval string, such as R2/P30D/2020-09-01 + * @param metric - A metric from the cost-insights configuration in app-config.yaml. + * @param intervals - An ISO 8601 repeating interval string, such as R2/P30D/2020-09-01 * https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals */ getDailyMetricData(metric: string, intervals: string): Promise; @@ -133,7 +133,7 @@ export type CostInsightsApi = { * The time period is supplied as a Duration rather than intervals, since this is always expected * to return data for two bucketed time period (e.g. month vs month, or quarter vs quarter). * - * @param options Options to use when fetching insights for a particular cloud product and + * @param options - Options to use when fetching insights for a particular cloud product and * interval time frame. */ getProductInsights(options: ProductInsightsOptions): Promise; diff --git a/plugins/cost-insights/src/utils/duration.ts b/plugins/cost-insights/src/utils/duration.ts index 6d7c8d4765..2e5614d484 100644 --- a/plugins/cost-insights/src/utils/duration.ts +++ b/plugins/cost-insights/src/utils/duration.ts @@ -23,8 +23,8 @@ export const DEFAULT_DURATION = Duration.P30D; /** * Derive the start date of a given period, assuming two repeating intervals. * - * @param duration see comment on Duration enum - * @param inclusiveEndDate from CostInsightsApi.getLastCompleteBillingDate + * @param duration - see comment on Duration enum + * @param inclusiveEndDate - from CostInsightsApi.getLastCompleteBillingDate */ export function inclusiveStartDateOf( duration: Duration, diff --git a/plugins/fossa/src/api/FossaApi.ts b/plugins/fossa/src/api/FossaApi.ts index 9a3932fea0..89f2792fdc 100644 --- a/plugins/fossa/src/api/FossaApi.ts +++ b/plugins/fossa/src/api/FossaApi.ts @@ -32,7 +32,7 @@ export type FossaApi = { /** * Get the finding summary for a list of projects * - * @param projectTitles a list of project titles in FOSSA + * @param projectTitles - a list of project titles in FOSSA */ getFindingSummaries( projectTitles: Array, @@ -41,7 +41,7 @@ export type FossaApi = { /** * Get the finding summary of a single project. * - * @param projectTitle the project title in FOSSA + * @param projectTitle - the project title in FOSSA */ getFindingSummary(projectTitle: string): Promise; }; diff --git a/plugins/jenkins/api-report.md b/plugins/jenkins/api-report.md index a6926c1639..61c5327fa1 100644 --- a/plugins/jenkins/api-report.md +++ b/plugins/jenkins/api-report.md @@ -49,17 +49,12 @@ export const JENKINS_ANNOTATION = 'jenkins.io/job-full-name'; // // @public (undocumented) export interface JenkinsApi { - // Warning: (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters - // Warning: (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters - // Warning: (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters // Warning: (ae-forgotten-export) The symbol "Build" needs to be exported by the entry point index.d.ts getBuild(options: { entity: EntityName; jobFullName: string; buildNumber: string; }): Promise; - // Warning: (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters - // Warning: (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters // Warning: (ae-forgotten-export) The symbol "Project" needs to be exported by the entry point index.d.ts getProjects(options: { entity: EntityRef; diff --git a/plugins/jenkins/src/api/JenkinsApi.ts b/plugins/jenkins/src/api/JenkinsApi.ts index 492e7f5198..65ac79b62b 100644 --- a/plugins/jenkins/src/api/JenkinsApi.ts +++ b/plugins/jenkins/src/api/JenkinsApi.ts @@ -77,12 +77,11 @@ export interface JenkinsApi { * and by the _Software Engineer_ using annotations agreed with the _Integrator_. * * Typically, a folder job will be identified and the backend plugin will recursively look for projects (jobs with builds) within that folder. - * - * @param options.entity the entity whose jobs should be retrieved. - * @param options.filter a filter on jobs. Currently this just takes a branch (and assumes certain structures in jenkins) */ getProjects(options: { + /** the entity whose jobs should be retrieved. */ entity: EntityRef; + /** a filter on jobs. Currently this just takes a branch (and assumes certain structures in jenkins) */ filter: { branch?: string }; }): Promise; @@ -92,9 +91,6 @@ export interface JenkinsApi { * This takes an entity to support selecting between multiple jenkins instances. * * TODO: abstract jobFullName (so we could support differentiating between the same named job on multiple instances). - * @param options.entity - * @param options.jobFullName - * @param options.buildNumber */ getBuild(options: { entity: EntityName; diff --git a/plugins/jenkins/src/components/useBuildWithSteps.ts b/plugins/jenkins/src/components/useBuildWithSteps.ts index 202d8b5275..2166b2a1a1 100644 --- a/plugins/jenkins/src/components/useBuildWithSteps.ts +++ b/plugins/jenkins/src/components/useBuildWithSteps.ts @@ -25,8 +25,8 @@ const INTERVAL_AMOUNT = 1500; /** * Hook to expose a specific build. - * @param jobFullName the full name of the project (job with builds, not a folder). e.g. "department-A/team-1/project-foo/master" - * @param buildNumber the number of the build. e.g. "13" + * @param jobFullName - the full name of the project (job with builds, not a folder). e.g. "department-A/team-1/project-foo/master" + * @param buildNumber - the number of the build. e.g. "13" */ export function useBuildWithSteps({ jobFullName, diff --git a/plugins/scaffolder-backend/api-report.md b/plugins/scaffolder-backend/api-report.md index 5c891b1802..45e4d0456b 100644 --- a/plugins/scaffolder-backend/api-report.md +++ b/plugins/scaffolder-backend/api-report.md @@ -286,7 +286,6 @@ export function fetchContents({ // @public export class OctokitProvider { constructor(integrations: ScmIntegrationRegistry); - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // Warning: (ae-forgotten-export) The symbol "OctokitIntegration" needs to be exported by the entry point index.d.ts getOctokit(repoUrl: string): Promise; } diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/OctokitProvider.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/OctokitProvider.ts index 9fdc6ced17..f287b403a2 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/OctokitProvider.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/github/OctokitProvider.ts @@ -52,7 +52,7 @@ export class OctokitProvider { /** * gets standard Octokit client based on repository URL. * - * @param repoUrl Repository URL + * @param repoUrl - Repository URL */ async getOctokit(repoUrl: string): Promise { const { owner, repo, host } = parseRepoUrl(repoUrl, this.integrations); diff --git a/plugins/scaffolder/api-report.md b/plugins/scaffolder/api-report.md index 5252e08299..0c3904adf6 100644 --- a/plugins/scaffolder/api-report.md +++ b/plugins/scaffolder/api-report.md @@ -90,7 +90,6 @@ export const EntityTagsPicker: ({ // @public export const EntityTagsPickerFieldExtension: () => null; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen // Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts // Warning: (ae-missing-release-tag) "FavouriteTemplate" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // @@ -179,8 +178,6 @@ export interface ScaffolderApi { // // (undocumented) listActions(): Promise; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen scaffold(templateName: string, values: Record): Promise; // Warning: (ae-forgotten-export) The symbol "LogEvent" needs to be exported by the entry point index.d.ts // @@ -225,8 +222,6 @@ export class ScaffolderClient implements ScaffolderApi { ): Promise; // (undocumented) listActions(): Promise; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen scaffold(templateName: string, values: Record): Promise; // (undocumented) streamLogs(opts: { taskId: string; after?: number }): Observable; diff --git a/plugins/scaffolder/src/api.ts b/plugins/scaffolder/src/api.ts index d7696fadde..ef59d4382f 100644 --- a/plugins/scaffolder/src/api.ts +++ b/plugins/scaffolder/src/api.ts @@ -67,8 +67,8 @@ export interface ScaffolderApi { * Executes the scaffolding of a component, given a template and its * parameter values. * - * @param templateName Name of the Template entity for the scaffolder to use. New project is going to be created out of this template. - * @param values Parameters for the template, e.g. name, description + * @param templateName - Name of the Template entity for the scaffolder to use. New project is going to be created out of this template. + * @param values - Parameters for the template, e.g. name, description */ scaffold(templateName: string, values: Record): Promise; @@ -149,8 +149,8 @@ export class ScaffolderClient implements ScaffolderApi { * Executes the scaffolding of a component, given a template and its * parameter values. * - * @param templateName Template name for the scaffolder to use. New project is going to be created out of this template. - * @param values Parameters for the template, e.g. name, description + * @param templateName - Template name for the scaffolder to use. New project is going to be created out of this template. + * @param values - Parameters for the template, e.g. name, description */ async scaffold( templateName: string, diff --git a/plugins/scaffolder/src/components/FavouriteTemplate/FavouriteTemplate.tsx b/plugins/scaffolder/src/components/FavouriteTemplate/FavouriteTemplate.tsx index 2c55ffdf88..6e8fe45b2f 100644 --- a/plugins/scaffolder/src/components/FavouriteTemplate/FavouriteTemplate.tsx +++ b/plugins/scaffolder/src/components/FavouriteTemplate/FavouriteTemplate.tsx @@ -52,7 +52,7 @@ export const favouriteTemplateIcon = (isStarred: boolean) => /** * IconButton for showing if a current entity is starred and adding/removing it from the favourite entities - * @param props MaterialUI IconButton props extended by required `entity` prop + * @param props - MaterialUI IconButton props extended by required `entity` prop */ export const FavouriteTemplate = (props: Props) => { const classes = useStyles(); diff --git a/plugins/search-backend-node/src/runPeriodically.ts b/plugins/search-backend-node/src/runPeriodically.ts index d5f5f87d7f..2f3104e221 100644 --- a/plugins/search-backend-node/src/runPeriodically.ts +++ b/plugins/search-backend-node/src/runPeriodically.ts @@ -19,8 +19,8 @@ * * Supports async functions, and silently ignores exceptions and rejections. * - * @param fn The function to run. May return a Promise. - * @param delayMs The delay between a completed function invocation and the + * @param fn - The function to run. May return a Promise. + * @param delayMs - The delay between a completed function invocation and the * next. * @returns A function that, when called, stops the invocation loop. */ diff --git a/plugins/techdocs-backend/src/service/router.ts b/plugins/techdocs-backend/src/service/router.ts index b54714101f..b807f00e7a 100644 --- a/plugins/techdocs-backend/src/service/router.ts +++ b/plugins/techdocs-backend/src/service/router.ts @@ -244,7 +244,7 @@ function getBearerToken(header?: string): string | undefined { /** * Create an event-stream response that emits the events 'log', 'error', and 'finish'. * - * @param res the response to write the event-stream to + * @param res - the response to write the event-stream to * @returns A tuple of callbacks to emit messages. A call to 'error' or 'finish' * will close the event-stream. */ @@ -293,7 +293,7 @@ export function createEventStream( /** * Create a HTTP response. This is used for the legacy non-event-stream implementation of the sync endpoint. * - * @param res the response to write the event-stream to + * @param res - the response to write the event-stream to * @returns A tuple of callbacks to emit messages. A call to 'error' or 'finish' * will close the event-stream. */ diff --git a/plugins/techdocs/api-report.md b/plugins/techdocs/api-report.md index c6b16be0b3..fc7b515167 100644 --- a/plugins/techdocs/api-report.md +++ b/plugins/techdocs/api-report.md @@ -223,9 +223,6 @@ export interface TechDocsApi { // @public (undocumented) export const techdocsApiRef: ApiRef; -// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" -// Warning: (tsdoc-undefined-tag) The TSDoc tag "@property" is not defined in this configuration // Warning: (ae-missing-release-tag) "TechDocsClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public @@ -245,11 +242,7 @@ export class TechDocsClient implements TechDocsApi { discoveryApi: DiscoveryApi; // (undocumented) getApiOrigin(): Promise; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' getEntityMetadata(entityId: EntityName): Promise; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' getTechDocsMetadata(entityId: EntityName): Promise; // (undocumented) identityApi: IdentityApi; @@ -384,9 +377,6 @@ export interface TechDocsStorageApi { // @public (undocumented) export const techdocsStorageApiRef: ApiRef; -// Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag -// Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" -// Warning: (tsdoc-undefined-tag) The TSDoc tag "@property" is not defined in this configuration // Warning: (ae-missing-release-tag) "TechDocsStorageClient" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public @@ -414,27 +404,11 @@ export class TechDocsStorageClient implements TechDocsStorageApi { ): Promise; // (undocumented) getBuilder(): Promise; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' - // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag - // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" - // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag - // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" getEntityDocs(entityId: EntityName, path: string): Promise; // (undocumented) getStorageUrl(): Promise; // (undocumented) identityApi: IdentityApi; - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' - // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen - // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}' - // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag - // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" - // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag - // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@" syncEntityDocs( entityId: EntityName, logHandler?: (line: string) => void, diff --git a/plugins/techdocs/src/client.ts b/plugins/techdocs/src/client.ts index f965cd7ced..3963637349 100644 --- a/plugins/techdocs/src/client.ts +++ b/plugins/techdocs/src/client.ts @@ -23,9 +23,7 @@ import { SyncResult, TechDocsApi, TechDocsStorageApi } from './api'; import { TechDocsEntityMetadata, TechDocsMetadata } from './types'; /** - * API to talk to techdocs-backend. - * - * @property {string} apiOrigin Set to techdocs.requestUrl as the URL for techdocs-backend API + * API to talk to `techdocs-backend`. */ export class TechDocsClient implements TechDocsApi { public configApi: Config; @@ -60,7 +58,7 @@ export class TechDocsClient implements TechDocsApi { * static files. It includes necessary data about the docs site. This method requests techdocs-backend * which retrieves the TechDocs metadata. * - * @param {EntityName} entityId Object containing entity data like name, namespace, etc. + * @param entityId - Object containing entity data like name, namespace, etc. */ async getTechDocsMetadata(entityId: EntityName): Promise { const { kind, namespace, name } = entityId; @@ -86,7 +84,7 @@ export class TechDocsClient implements TechDocsApi { * This method requests techdocs-backend which uses the catalog APIs to respond with filtered * information required here. * - * @param {EntityName} entityId Object containing entity data like name, namespace, etc. + * @param entityId - Object containing entity data like name, namespace, etc. */ async getEntityMetadata( entityId: EntityName, @@ -111,8 +109,6 @@ export class TechDocsClient implements TechDocsApi { /** * API which talks to TechDocs storage to fetch files to render. - * - * @property {string} apiOrigin Set to techdocs.requestUrl as the URL for techdocs-backend API */ export class TechDocsStorageClient implements TechDocsStorageApi { public configApi: Config; @@ -154,10 +150,10 @@ export class TechDocsStorageClient implements TechDocsStorageApi { /** * Fetch HTML content as text for an individual docs page in an entity's docs site. * - * @param {EntityName} entityId Object containing entity data like name, namespace, etc. - * @param {string} path The unique path to an individual docs page e.g. overview/what-is-new - * @returns {string} HTML content of the docs page as string - * @throws {Error} Throws error when the page is not found. + * @param entityId - Object containing entity data like name, namespace, etc. + * @param path - The unique path to an individual docs page e.g. overview/what-is-new + * @returns HTML content of the docs page as string + * @throws Throws error when the page is not found. */ async getEntityDocs(entityId: EntityName, path: string): Promise { const { kind, namespace, name } = entityId; @@ -198,10 +194,10 @@ export class TechDocsStorageClient implements TechDocsStorageApi { /** * Check if docs are on the latest version and trigger rebuild if not * - * @param {EntityName} entityId Object containing entity data like name, namespace, etc. - * @param {Function} logHandler Callback to receive log messages from the build process - * @returns {SyncResult} Whether documents are currently synchronized to newest version - * @throws {Error} Throws error on error from sync endpoint in Techdocs Backend + * @param entityId - Object containing entity data like name, namespace, etc. + * @param logHandler - Callback to receive log messages from the build process + * @returns Whether documents are currently synchronized to newest version + * @throws Throws error on error from sync endpoint in Techdocs Backend */ async syncEntityDocs( entityId: EntityName,