Got rid of the last brace-typed and hyphen-less params etc

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

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);

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,

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,

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,

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,

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,

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

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
  *
  */

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)
 //

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;
   /**

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 {

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 {

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.
  *
- * <code>
- * <!--
+ * ```
  *   <Card>
  *     <CardMedia>
  *       <ItemCardHeader title="My Card" subtitle="neat!" />
@@ -55,10 +54,9 @@ type ItemCardProps = {
  *       </Button>
  *     </CardActions>
  *   </Card>
- * -->
- * </code>
+ * ```
  *
- * @deprecated Use plain MUI <Card> and composable helpers instead.
+ * @deprecated Use plain MUI `<Card>` and composable helpers instead.
  * @see https://material-ui.com/components/cards/
  */
 export function ItemCard(props: ItemCardProps) {

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,

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;

packages/integration/api-report.md

@@ -432,9 +432,4 @@ export class SingleInstanceGithubCredentialsProvider
   static create: (config: GitHubIntegrationConfig) => GithubCredentialsProvider;
   getCredentials(opts: { url: string }): Promise<GithubCredentials>;
 }
-
-// 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 "{@"
 ```

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;
 };

packages/techdocs-common/api-report.md

@@ -172,12 +172,6 @@ export interface PublisherBase {
   fetchTechDocsMetadata(entityName: EntityName): Promise<TechDocsMetadata>;
   getReadiness(): Promise<ReadinessResponse>;
   hasDocsBeenGenerated(entityName: Entity): Promise<boolean>;
-  // 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<void>;
   // 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 "{@"
 ```

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,

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,

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,

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<void>;
 }